Sovrain
  1. Documentation
  2. Identity provider

Explanation

Admin API access

Why a script gets Admin API access through an admin's approval in the browser, why it acts as that admin, and why the access ends on its own.

The Admin API lets a script do what an admin does in the admin pages: invite people, suspend them, change groups, set up applications. That makes an API token as powerful as an admin’s sign-in. Sovrain therefore hands out API access the way it treats an admin’s sign-in: a person approves it, it acts as that person, and it does not last forever.

A person approves, in the browser

A script that wants access asks Sovrain for a short code and shows it. An admin opens Sovrain in their own browser, enters the code and chooses what the script may do. This is the OAuth 2.0 device authorization grant, made for programs that cannot show a sign-in page themselves, such as a script in a terminal or a job on a server.

The point of the detour through the browser is that the script never handles the admin’s credentials. The admin signs in where they always do, with their password and second step, and Sovrain asks for a sign-in from the last 5 minutes before it lets them approve. The script only ever holds tokens, which can be revoked without touching the admin’s password.

The approval page also gives the admin a chance to notice something wrong. It shows where the request came from (the IP address and the program) and how long ago it was made, and marks the scopes that cannot be undone or that reach application secrets. A code is valid for 10 minutes, so an old code shown somewhere cannot be approved by mistake days later.

The token acts as the admin who approved it

A token from the Admin API has no rights of its own. Every call runs as the admin who approved it, narrowed to the scopes they ticked. A scope can take rights away, never add them: a token with every scope can still do only what that admin can do in the admin pages, under the same rules and with the same refusal messages.

Because the token stands for a person, Sovrain checks the person on every call, not only when the token is issued: the account must still be usable, the admin must still be in Owners or Admins, and their deadline to set up two-step sign-in must not have passed. An admin who loses admin rights loses their scripts’ access with the next call.

For the same reason, a grant ends when something changes about the admin that could have been used to approve it. If the password changes, or the second steps are reset or removed, whoever knew the old ones might have approved a grant; so every grant approved before goes. Suspending or removing the admin, or taking them out of Owners and Admins, ends their grants too. An ended grant stays ended, even if the admin comes back: access starts again only when someone approves a new request. The exact list is in Admin API › When a grant ends.

Tying each token to a person also answers the question “who did this?”. Every authorized call is recorded with its grant, and the API access pages show, for each grant, the admin it acts as, the scopes, and the calls of the last day. Limits follow the person where it matters: the budget of invitation emails is per admin, so approving more grants does not buy more emails.

No service accounts, no client secrets

Many APIs offer a service account or the client_credentials grant: a client ID and secret that a program presents to get a token, with no person involved. Sovrain has neither. The only client that can get an Admin API token is the built-in public client cli, which has no secret, and the token endpoint refuses client_credentials from every client.

A service account would be an admin that cannot sign in, cannot set up two-step sign-in, cannot be suspended because someone left, and whose secret lives in configuration files for years. The approach Sovrain takes keeps every route to the API behind a person who signed in with their second step.

The cost is real, and you should plan for it. A script stops when the admin who approved it leaves, changes their password or loses their admin rights, and every integration needs a person to approve it again at least every 90 days. If a script must keep running, have it approved by an admin who is expected to stay, and treat the re-approval as a regular task, like renewing a certificate.

Why access ends on its own

A grant has two clocks. It ends 30 days after the script last refreshed its token, and 90 days after approval in any case.

The 30-day clock cleans up after scripts that are no longer used. Only refreshing a token keeps the grant alive; calls do not. A script that nobody runs any more loses its access within a month, without anyone having to remember to revoke it.

The 90-day clock makes sure that a person looks at every grant regularly. When an admin approves again, they see the scopes once more and can drop the ones the script no longer needs.

Inside a grant, the tokens are short-lived and single-use. An access token is valid for 10 minutes, and each refresh token works once and is replaced by a new one. If a refresh token that was already used shows up again, someone has a copy, and Sovrain revokes the whole grant. Revocation does not wait for tokens to expire: Sovrain checks the grant on every call, so a revoked grant stops working at the next call.

The API accepts tokens only in the header

The Admin API reads the token from the Authorization header only, never from a cookie or the query string. A browser never adds that header by itself, so a page on another site cannot make a signed-in admin’s browser call the API for it. That is also why the API answers cross-origin requests from any site: without the token, a request does nothing.