Admin API
Host, authentication, scopes, conventions, paging, errors and rate limit of the Sovrain Admin REST API.
The Admin API manages the users, invitations, groups and applications of one organization over JSON and HTTPS. It does what an admin can do in the admin pages, within the scopes the admin approved for the token.
| Page | Covers |
|---|---|
| Users | /users: list, read, profile, attributes, groups, suspend, restore, remove, resend invitation |
| Invitations | /invites: invite people by email or login name |
| Groups | /groups: list, read, create, change, delete, members |
| Applications | /apps: list, read, create, change, type, enable, disable, delete, group access |
| OpenID Connect clients | /apps/{slug}/oidc: client settings, secret, redirect URIs, sign-out, claims |
| SAML configuration | /apps/{slug}/saml: service provider, signing, encryption, ACS, metadata, mappings, keys, certificates |
| SCIM provisioning | /apps/{slug}/scim: connection, token, test, mapping, scope, retries, reconcile |
Host and base path
Every endpoint is on the organization’s own host, under /api/v1:
https://acme.sovrain.net/api/v1
- When the organization has a primary custom domain, use that domain. Requests to
acme.sovrain.netare then answered with a307redirect to it. - On
sovrain.net(no organization), every/api/**path answers404with{"error":"not_found","error_description":"The API is served on an organization's own host."}.
There is no OpenAPI document.
Authentication
Every call needs an access token in the Authorization header:
Authorization: Bearer <access token>
Cookies and tokens in the query string are not accepted.
Tokens come from the OAuth 2.0 device authorization grant (RFC 8628) with the built-in public client cli. Step by
step: Get an Admin API token. Why the API is reached this way:
About Admin API access.
| Step | Request | Result |
|---|---|---|
| 1. Ask for a code | POST /oidc/device_authorization, form client_id=cli and optionally scope=<space-separated scopes> | device_code, user_code (XXXX-XXXX), verification_uri (/device), verification_uri_complete, expires_in 600, interval 5 |
| 2. An admin approves | The admin opens https://acme.sovrain.net/device, enters the code, and selects Approve | The admin can untick scopes; never add any |
| 3. Poll for the token | POST /oidc/token, form grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code, client_id=cli | access_token, token_type Bearer, expires_in 600, refresh_token, scope |
| Refresh | POST /oidc/token, form grant_type=refresh_token, refresh_token, client_id=cli | A new access token and a new refresh token |
| Revoke | POST /oidc/revoke, form token=<refresh token>, client_id=cli | 200 {}; the whole grant is revoked |
Rules of the device grant:
client_idmust becli. Another value answers401 invalid_clientwhen asking for a code and400 unauthorized_clientwhen polling with a device code. Noclient_secretand noAuthorizationheader may be sent.- Leaving
scopeout offers all 10 scopes to the approver. Unknown scope names are dropped; ascopewith only unknown names answers400 invalid_scope. - Only a member of the built-in group Owners or Admins can approve. Approving needs a sign-in less than 5 minutes old.
- Polling errors, all
400:authorization_pending,slow_down(polled faster thaninterval; the interval grows by 5 seconds for the rest of the request),access_denied(the approver selected Deny),expired_token(expired, already used or unknown). - A refresh token works once. Presenting a used refresh token again revokes the whole grant. A token used more than
a day ago may instead be refused as unknown (
invalid_grant), and the grant stays.
Lifetimes
| Item | Value |
|---|---|
| Device code | 10 minutes |
| Access token | 10 minutes; an RS256 JWT with header typ: at+jwt |
| Grant | Ends 30 days after its last refresh. Each refresh sets the end to 30 days from then. API calls do not extend it. |
| Grant, hard limit | 90 days after approval. A refresh never extends a grant past it. |
When a grant ends
Besides running out, a grant ends when:
- it is revoked: with
POST /oidc/revoke, with Revoke on Profile › API access (/profile/api-access) by the admin who approved it, or with Revoke on Admin › API access (/admin/api-access) by any admin; - a refresh token of the grant that was already used is presented again (see the rules above);
- the admin who approved it is suspended or removed;
- the admin leaves both Owners and Admins;
- the admin’s password changes, whether the admin changes it or sets it through a password reset link;
- an admin resets the admin’s two-step sign-in, or removes one of the admin’s second steps;
- the admin resets their own two-step sign-in through a recovery link.
An ended grant stays ended, also when the admin is restored or made an admin again. From that moment, calls with
its access tokens answer 401 invalid_token and refreshing answers 400 invalid_grant.
Grants are listed, with their calls of the last 24 hours, on Profile › API access for one’s own grants and on Admin › API access for everyone’s. Ended grants stay listed for 7 days.
Checks on every call
In this order:
- A token is present and valid: issued by this organization, RS256,
typ: at+jwt, not expired, at most 8 KiB, issued tocli, its grant active, its account usable. Otherwise401 invalid_token. - The caller is still a member of Owners or Admins. Otherwise
403 access_denied. - The caller’s deadline to set up two-step sign-in has not passed. Otherwise
403 access_denied. - The path exists. Otherwise
404in the generic format (see Errors). An unauthenticated caller gets401before404. - The route’s scope is in the token. Otherwise
403 insufficient_scope. - The grant is under its rate limit. Otherwise
429 rate_limited.
Every authorized call is recorded with its method, path template, scope, status and client IP. The records are kept for 1 day.
Scopes
A scope limits what the token may do. It never gives the admin more rights than the admin already has.
| Scope | Allows | Marked on the approval page |
|---|---|---|
users:read | GET /users, GET /users/{id} | |
users:write | PATCH /users/{id}, PUT /users/{id}/attributes, PUT /users/{id}/groups, POST /users/{id}/suspend, POST /users/{id}/restore | |
users:delete | DELETE /users/{id} | cannot be undone |
invites:write | POST /invites, POST /users/{id}/invite | |
groups:read | GET /groups, GET /groups/{id} | |
groups:write | POST /groups, PATCH /groups/{id}, PUT and DELETE /groups/{id}/members/{userId}; also needed for POST /invites with a non-empty groups | |
groups:delete | DELETE /groups/{id} | cannot be undone |
apps:read | GET /apps, GET /apps/{slug}, GET /apps/{slug}/oidc, GET /apps/{slug}/saml, GET /apps/{slug}/saml/signing-keys/{keyId}/certificate, GET /apps/{slug}/scim | |
apps:write | Every other application, OIDC, SAML and SCIM call, including generating client secrets and setting SCIM tokens | can read and rotate app secrets |
apps:delete | DELETE /apps/{slug} | cannot be undone |
Conventions
- Requests and responses are JSON (
Content-Type: application/json). Keys aresnake_case. - Users and groups are addressed by their public
id. Applications are addressed by theirslug. Items inside an application (redirect URIs, claims, ACS endpoints, mappings, keys, certificates) are addressed by a numericid. - Public ids are 22 characters from
23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz. - Times are ISO 8601 in UTC with
Z, with 0 to 9 fractional digits, for example2026-11-17T09:30:00.123456Z. - Enum values are sent in upper case (
"OIDC","CONFIDENTIAL","HTTP_POST"). Some responses return them in lower case; each endpoint shows which. - Request bodies are read strictly: an unknown field, a value of the wrong type or a misspelled enum value answers
400 invalid_request. The SCIM endpoints are the exception: they ignore unknown fields. - A
PUTreplaces the whole setting it addresses, and a boolean left out of it isfalse, even when the default of a new application istrue, except where an endpoint’s table says “Left out: unchanged”. APATCHchanges only the fields it contains. - The request body limit is 2 MB.
- Responses that carry a secret have
Cache-Control: no-storeandPragma: no-cache.
CORS
The API answers cross-origin requests: a preflight OPTIONS needs no token and answers
Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE and the requested
headers. The SCIM endpoints (/apps/{slug}/scim…) are the exception: they do not answer the preflight, so call them
from a server, not from a browser page on another origin.
Lists and paging
Every list has this shape:
{
"items": [ ],
"next_cursor": null
}
| Endpoint | Paging |
|---|---|
GET /users | limit 1 to 200, default 50. next_cursor is a string while more users follow; pass it back unchanged as cursor. |
GET /groups, GET /apps | Everything in one page; next_cursor is always null |
A cursor is opaque. A cursor that Sovrain did not issue answers
422 {"error":"refused","error_description":"Invalid cursor: 'x'; pass back next_cursor unchanged"}.
Errors
Errors have this shape:
{
"error": "refused",
"error_description": "Slug already in use: grafana"
}
error_description is written for people and can change. Program against error and the status.
| Status | error | When |
|---|---|---|
| 400 | invalid_request | The body is not valid JSON, has an unknown field or a value of the wrong type, misses a required field (Send 'name'), or a number in the path or query is not a number |
| 401 | invalid_token | No token, an invalid or expired token, a token of another organization, a revoked grant. With WWW-Authenticate: Bearer error="invalid_token" |
| 403 | access_denied | The caller is no longer an admin, or the caller’s deadline for two-step sign-in has passed |
| 403 | insufficient_scope | The token lacks the route’s scope, for example This token lacks the scope 'users:write'. With WWW-Authenticate: Bearer error="insufficient_scope", scope="users:write" |
| 404 | not_found | Unknown user, group or application, for example Unknown user: external id 'x' |
| 404 | (generic format) | Unknown path |
| 422 | refused | A rule of the product refused the request. The text is the same as in the admin pages. |
| 429 | rate_limited | Over the grant’s rate limit, or over the invitation email budget (Invitation email limit reached. Try again in an hour.) |
| 500 | (generic format or empty) | A server fault |
The 401, 403 and the rate-limit 429 refusals have Cache-Control: no-store.
The generic format, used for an unknown path, a 429 raised before the API itself and server faults:
{
"timestamp": 1794914492344,
"status": 404,
"error": "Not Found",
"path": "/api/v1/nope"
}
A request whose path, query or headers contain a pattern of a known attack (for example ${jndi: or <script) is
refused before it reaches the API with 400, Content-Type: text/plain and a body such as ___:484daa1a.
Rate limit
| Limit | Value |
|---|---|
| Calls per grant | 600 per 60 seconds; the budget refills in full every 60 seconds |
| Invitation emails per admin | 200 per hour, shared by POST /invites and POST /users/{id}/invite |
Over the limit: 429 with
{"error":"rate_limited","error_description":"Too many calls with this grant; wait a minute and try again."}.
Other limits of the token endpoints: Limits.
Not in the API
These are managed in the admin pages only:
- the two-step sign-in policy, account recovery, branding, the custom domain, delegations and backups;
- the attribute bank (attribute values can be set through the API, see Users);
- the OpenID Connect signing keys of the organization;
- the SAML test sign-in, the SAML metadata file upload;
- the SCIM activity list, per-job retry and cancel, Force sync…, drift removal and the user lookup.
There is no client_credentials grant: every token acts as the admin who approved it.