How-to guide
Get an Admin API token
Get an access token for the Admin API through the device flow, keep it fresh and revoke it when you are done.
This guide gets an access token for the Sovrain Admin API from a terminal or a script. An admin approves the request in the browser, and the script then calls the API with that admin’s rights, narrowed to the scopes they approved.
Before you start
- You need an admin of the organization, a member of Owners or Admins, to approve the request. Only they can.
- Decide which scopes the script needs. The ten scopes are listed in Admin API;
for example
users:read groups:readto read people and groups. The scopesusers:delete,groups:delete,apps:writeandapps:deleteare marked as dangerous on the approval page.
There is no client_credentials grant and no service account. Every token belongs to the admin who approved it, and
the only client that can get one is the built-in client cli. See
About Admin API access.
Get the token
Ask for a device code:
curl https://acme.sovrain.net/oidc/device_authorization \ -d client_id=cli \ --data-urlencode "scope=users:read groups:read"{ "device_code": "Hq3…", "user_code": "BCDF-GHJK", "verification_uri": "https://acme.sovrain.net/device", "verification_uri_complete": "https://acme.sovrain.net/device?code=BCDF-GHJK", "expires_in": 600, "interval": 5 }Without
scope, the approver is offered all ten scopes. Scope names Sovrain does not know are dropped; ascopewith none it knows is refused withinvalid_scope.Have the admin open
verification_uri_completewithin 10 minutes, check the code and the Requested from, Program and When details, tick the scopes and select Approve. Sovrain may ask them to sign in again first. The admin can approve fewer scopes than you asked for, never more. See Approve command-line access.Meanwhile, ask the token endpoint every
intervalseconds:curl https://acme.sovrain.net/oidc/token \ -d grant_type=urn:ietf:params:oauth:grant-type:device_code \ -d device_code="$DEVICE_CODE" \ -d client_id=cliUntil the admin decides, the answer is
400with one of these errors:errorWhat to do authorization_pendingWait intervalseconds and ask againslow_downYou asked too soon. Add 5 seconds to your interval for the rest of the flow access_deniedThe admin selected Deny. Stop expired_tokenThe code expired or was already used. Start again at step 1 After approval the answer is:
{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 600, "refresh_token": "Xk9…", "scope": "users:read groups:read" }Call the API with the access token in the
Authorizationheader:curl https://acme.sovrain.net/api/v1/users -H "Authorization: Bearer $ACCESS_TOKEN"Do not send
client_secretor a BasicAuthorizationheader to the token endpoint:clihas no secret, and either one is refused.
Keep the token fresh
The access token is valid for 10 minutes. Before it expires, refresh it:
curl https://acme.sovrain.net/oidc/token \
-d grant_type=refresh_token \
-d refresh_token="$REFRESH_TOKEN" \
-d client_id=cli
- Send
client_id=clias a form parameter. Without it the request is treated as an app’s refresh and fails. - Store the new
refresh_tokenfrom every answer. A refresh token works once; using an old one again revokes the whole grant. - Refresh at least every 30 days, even if the script calls the API less often: API calls do not keep the grant alive. After 90 days no refresh helps; run the device flow again. The exact rules are in Admin API › Lifetimes.
Revoke the token when you are done
curl https://acme.sovrain.net/oidc/revoke -d token="$REFRESH_TOKEN" -d client_id=cli
Sovrain answers 200 {} and ends the grant. The admin can also select Revoke on the API access page of their
profile, and any admin can revoke it under API access in the admin area; see
Review API access.
When the token stops working
| Answer | What to do |
|---|---|
401 invalid_token from the API | The access token has expired, or the grant has ended. Refresh, then call again |
400 invalid_grant from a refresh | The grant has ended. Run the device flow again, with an admin who still has access |
403 access_denied | Usually the approving admin’s deadline to set up two-step sign-in has passed. Have them set it up in the browser, then call again |
429 rate_limited | Wait a minute. A grant may make 600 calls a minute |
A grant ends early when something changes about the admin who approved it, for example when they are suspended, leave Owners and Admins, or change their password. The full list is in Admin API › When a grant ends; why tokens work this way is in About Admin API access.
To use the token, see Automate onboarding with the Admin API, Offboard people with the Admin API and Configure apps with the Admin API.