Sovrain
  1. Documentation
  2. Identity provider
  3. For developers

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.

PageCovers
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.net are then answered with a 307 redirect to it.
  • On sovrain.net (no organization), every /api/** path answers 404 with {"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.

StepRequestResult
1. Ask for a codePOST /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 approvesThe admin opens https://acme.sovrain.net/device, enters the code, and selects ApproveThe admin can untick scopes; never add any
3. Poll for the tokenPOST /oidc/token, form grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code, client_id=cliaccess_token, token_type Bearer, expires_in 600, refresh_token, scope
RefreshPOST /oidc/token, form grant_type=refresh_token, refresh_token, client_id=cliA new access token and a new refresh token
RevokePOST /oidc/revoke, form token=<refresh token>, client_id=cli200 {}; the whole grant is revoked

Rules of the device grant:

  • client_id must be cli. Another value answers 401 invalid_client when asking for a code and 400 unauthorized_client when polling with a device code. No client_secret and no Authorization header may be sent.
  • Leaving scope out offers all 10 scopes to the approver. Unknown scope names are dropped; a scope with only unknown names answers 400 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 than interval; 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

ItemValue
Device code10 minutes
Access token10 minutes; an RS256 JWT with header typ: at+jwt
GrantEnds 30 days after its last refresh. Each refresh sets the end to 30 days from then. API calls do not extend it.
Grant, hard limit90 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:

  1. A token is present and valid: issued by this organization, RS256, typ: at+jwt, not expired, at most 8 KiB, issued to cli, its grant active, its account usable. Otherwise 401 invalid_token.
  2. The caller is still a member of Owners or Admins. Otherwise 403 access_denied.
  3. The caller’s deadline to set up two-step sign-in has not passed. Otherwise 403 access_denied.
  4. The path exists. Otherwise 404 in the generic format (see Errors). An unauthenticated caller gets 401 before 404.
  5. The route’s scope is in the token. Otherwise 403 insufficient_scope.
  6. 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.

ScopeAllowsMarked on the approval page
users:readGET /users, GET /users/{id}
users:writePATCH /users/{id}, PUT /users/{id}/attributes, PUT /users/{id}/groups, POST /users/{id}/suspend, POST /users/{id}/restore
users:deleteDELETE /users/{id}cannot be undone
invites:writePOST /invites, POST /users/{id}/invite
groups:readGET /groups, GET /groups/{id}
groups:writePOST /groups, PATCH /groups/{id}, PUT and DELETE /groups/{id}/members/{userId}; also needed for POST /invites with a non-empty groups
groups:deleteDELETE /groups/{id}cannot be undone
apps:readGET /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:writeEvery other application, OIDC, SAML and SCIM call, including generating client secrets and setting SCIM tokenscan read and rotate app secrets
apps:deleteDELETE /apps/{slug}cannot be undone

Conventions

  • Requests and responses are JSON (Content-Type: application/json). Keys are snake_case.
  • Users and groups are addressed by their public id. Applications are addressed by their slug. Items inside an application (redirect URIs, claims, ACS endpoints, mappings, keys, certificates) are addressed by a numeric id.
  • Public ids are 22 characters from 23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz.
  • Times are ISO 8601 in UTC with Z, with 0 to 9 fractional digits, for example 2026-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 PUT replaces the whole setting it addresses, and a boolean left out of it is false, even when the default of a new application is true, except where an endpoint’s table says “Left out: unchanged”. A PATCH changes only the fields it contains.
  • The request body limit is 2 MB.
  • Responses that carry a secret have Cache-Control: no-store and Pragma: 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
}
EndpointPaging
GET /userslimit 1 to 200, default 50. next_cursor is a string while more users follow; pass it back unchanged as cursor.
GET /groups, GET /appsEverything 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.

StatuserrorWhen
400invalid_requestThe 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
401invalid_tokenNo token, an invalid or expired token, a token of another organization, a revoked grant. With WWW-Authenticate: Bearer error="invalid_token"
403access_deniedThe caller is no longer an admin, or the caller’s deadline for two-step sign-in has passed
403insufficient_scopeThe 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"
404not_foundUnknown user, group or application, for example Unknown user: external id 'x'
404(generic format)Unknown path
422refusedA rule of the product refused the request. The text is the same as in the admin pages.
429rate_limitedOver 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

LimitValue
Calls per grant600 per 60 seconds; the budget refills in full every 60 seconds
Invitation emails per admin200 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.