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

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:read to read people and groups. The scopes users:delete, groups:delete, apps:write and apps:delete are 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

  1. 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; a scope with none it knows is refused with invalid_scope.

  2. Have the admin open verification_uri_complete within 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.

  3. Meanwhile, ask the token endpoint every interval seconds:

    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=cli
    

    Until the admin decides, the answer is 400 with one of these errors:

    errorWhat to do
    authorization_pendingWait interval seconds and ask again
    slow_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"
    }
    
  4. Call the API with the access token in the Authorization header:

    curl https://acme.sovrain.net/api/v1/users -H "Authorization: Bearer $ACCESS_TOKEN"
    

    Do not send client_secret or a Basic Authorization header to the token endpoint: cli has 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=cli as a form parameter. Without it the request is treated as an app’s refresh and fails.
  • Store the new refresh_token from 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

AnswerWhat to do
401 invalid_token from the APIThe access token has expired, or the grant has ended. Refresh, then call again
400 invalid_grant from a refreshThe grant has ended. Run the device flow again, with an admin who still has access
403 access_deniedUsually 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_limitedWait 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.