Scopes
This page helps you pick the scope a token needs for the operations you call.
A scope is what a client asks for when it requests a token. For the APIs, each scope is a permission on the authserver resource, written authserver: and the permission, and a token carries only the scopes its client or user holds.
Give each integration the smallest scope that does its job. A service that creates and disables users needs authserver:manage-users, not authserver:manage: it can then manage every user who isn’t an administrator, and nothing else.
The Admin API scopes
Section titled “The Admin API scopes”| Scope | Reads | Writes |
|---|---|---|
authserver:admin-read |
Every Admin API operation that reads, administrators included, except a client’s secret | Nothing |
authserver:manage-users |
Users and groups, with their attributes, sessions, consents, memberships and permissions | The same, except administrators and administrative permissions |
authserver:manage-clients |
Clients, their secrets included, except an administrator client’s or one listed for the authserver resource |
Clients, except administrator clients, adding the authserver resource to a client’s introspection resources, and setting the secret of a client listed for it |
authserver:manage-settings |
Settings, email templates, brands and their uploaded files, resources and their permissions, legal documents, signing keys, and the audit log | Settings except email and audit logging, brands and their uploaded files, resources and their permissions, legal documents, signing keys. Not email templates |
authserver:manage |
Everything | Everything, administrators included |
Every operation that reads accepts authserver:admin-read, the scope of its domain, or authserver:manage. Every operation that writes accepts the scope of its domain or authserver:manage. The phone countries (GET /api/v1/admin/phone-countries) belong to no domain, so every administrative scope reads them.
Two reads are different. A client’s secret (GET /api/v1/admin/clients/{id}/secret) is a credential, so authserver:admin-read doesn’t reach it. It takes authserver:manage-clients or authserver:manage, and authserver:manage alone for an administrator client or a client listed for the authserver resource.
A user’s export (GET /api/v1/admin/users/{id}/export) holds the user’s audit events, which belong to the settings domain, so it needs a token that reads both users and the audit log. It takes authserver:admin-read, authserver:manage, or authserver:manage-users together with authserver:manage-settings. A token with authserver:manage-users alone is refused.
A token with none of the scopes an operation accepts is answered 403 with the error code INSUFFICIENT_SCOPE.
The four granular scopes stop short of administrators: they read them, but they can’t create, change or delete one. Only authserver:manage does that, as Administrators explains.
The Account API scope
Section titled “The Account API scope”Every Account API operation takes authserver:manage-account, on a token issued for a user. It isn’t an administrative scope: a token carrying it reaches the user’s own account and nothing else. That still means the user’s profile, sessions and consents, and every user holds the manage-account permission from the moment they’re created, so the user decides which clients get it.
Any client that signs users in, with the authorization code or the implicit flow, can ask for it, and gets it once the user has approved it on the consent screen. Whatever the client’s Ask users for consent says, the user is asked the first time. Their answer is kept, so refreshes go through without asking, and so do later sign-ins, prompt=none included, unless the client is public with Remember consent off. A user who unticks it, or withdraws it under Account, Consents, is asked again. Until they’ve approved it, prompt=none is answered consent_required and a refresh renewing it invalid_grant. Consent required has the whole rule.
The admin console’s own client is the one exception: it gets authserver:manage-account with no screen, since that’s how users reach their own Account pages. It’s also the only client whose token can delete the account, POST /api/v1/account/deletion, or download its data, GET /api/v1/account/export. A token any other client holds is refused 403 with CLIENT_NOT_ALLOWED, so an app the user granted authserver:manage-account can change their account but can’t delete it or download it. A client allowed to request the administrative scopes is asked like any other. The password grant shows no screen at all, so a client using it gets authserver:manage-account as it gets any scope the user holds: the user has typed their password into it.
The domains
Section titled “The domains”Each Admin API operation belongs to one domain, and the domain decides which granular scope reaches it:
| Domain | Operations |
|---|---|
| Users | Users, user attributes, user sessions, user consents, the legal documents each user accepted, read only, groups, group members, group attributes, and the permissions of users and groups |
| Clients | Clients, with their authentication, flows, redirect URIs, sign-out redirect URIs, web origins, tokens, permissions, introspection resources, sessions, logo and secret, and the legal documents that apply to each, read only |
| Settings | General, email, session, token and audit log settings, email templates, brands and their uploaded files, the built-in themes, signing keys, resources and their permissions, legal documents and the clients each applies to, and the audit log |
Administrative scopes on a user’s behalf
Section titled “Administrative scopes on a user’s behalf”A token from the client credentials flow carries the client’s own permissions. A token your app gets for a signed-in user, through the authorization code flow, carries the scopes that user holds. For the six administrative scopes, authserver:manage, authserver:admin-read, authserver:manage-users, authserver:manage-clients, authserver:manage-settings and authserver:browser-sessions, that token would reach the Admin API with the user’s administrative rights. So only a client allowed to request the administrative scopes can get one on a user’s behalf:
- the admin console’s own client, always;
- any other client an operator has allowed, with the May request administrative scopes switch on the client’s settings in the admin console, or with
PUT /api/v1/admin/clients/{id}/administrative-scopes. Onlyauthserver:manageturns it on or off.
A new client starts not allowed, including one that registered itself. The rule holds on the authorization code flow, prompt=none included, on the implicit flow, and on the refresh token and password grants. A client that isn’t allowed and asks for one of these scopes is refused, never handed a narrower token: invalid_scope from the authorization endpoint and on the password grant, and invalid_grant when it redeems a code or refreshes. The authorization endpoint and the token endpoint have the exact answers.
The client credentials flow isn’t affected: a client holding an administrative permission of its own keeps asking for it there.