Roles and permissions
SeekAuth puts what a caller may do into the access token, so your backend checks a list instead of looking anything up. Three things work together:
- An API is a server of yours that takes access tokens. Its audience is the name tokens for it carry in
aud, such asorders-api. - A permission belongs to one API and names one thing that may be done with it, such as
orders:readorlinks:write. - A role is a named set of permissions, such as
editor. Users and machine clients are given roles, never single permissions.
All three are set up per environment, on the APIs and roles page of the dashboard or with the management API. Development and production each have their own.
Create an API for each backend that takes tokens. Its audience is 1 to 100 letters, digits and - _ . : /, and is unique in the environment. An API belongs to one app of the group; tokens for it carry that app’s roles.
{ "audience": "orders-api", "name": "Orders", "app_id": "<app id>" }app_id can be left out in a group of one app. Every environment also has the built-in account API, which belongs to no app: it is the account API each user has for their own account.
When an API (or its app) is deleted, its audience stays held for that app: servers of that app may still trust tokens naming it, so only the same app can create an API with that audience again. Another app asking for it gets 409.
Permissions
Section titled “Permissions”A permission is 1 to 100 letters, digits and - _ . : / (written like links:write), unique within its API.
{ "name": "orders:write" }A role has a name (letters, digits and - _ . :), a set of permissions, and two more settings:
| Setting | Meaning |
|---|---|
app_id |
The app the role belongs to. Leave it out (or null) for a group-wide role, which tokens for every app’s APIs carry. It cannot be changed once the role exists. |
requires_aal2 |
“Requires two-step login”: the role counts only in a session that passed a second factor (acr aal2). In any other session it is left out of the token, silently. |
{ "name": "editor", "permission_ids": ["<orders:write id>", "<orders:read id>"] }Changing a role (PATCH /v1/environments/:id/roles/:role) replaces it: send the name, requires_aal2 and every permission it should keep. A role with requires_aal2 does not make anyone log in with two steps; it only stays out of tokens from sessions that did not. To ask for a second factor, see Two-step login.
Giving roles to users
Section titled “Giving roles to users”On the Users page, or with the management API. The list you send replaces the user’s roles:
{ "role_ids": ["<editor role id>"] }Roles are worked out each time a token is issued. A change reaches the user’s apps with their next access token: within the access token’s lifetime (five minutes unless the environment says otherwise, see Lifetimes), since an app renews its token before it expires. A token already issued keeps the roles it was issued with.
Giving roles to machine clients
Section titled “Giving roles to machine clients”A machine client has roles of its own, set on its page under Clients:
{ "role_ids": ["<fulfilment role id>"] }Only machine clients have roles of their own; a user’s roles come from the user. A role that requires two-step login never counts for a machine client.
What the token carries
Section titled “What the token carries”An access token is for one audience, and carries:
roles: the user’s group-wide roles, and their roles of the app that owns the token’s audience;permissions: the permissions of those roles that belong to the token’s audience, and none of any other API.
So a token for orders-api says what the user may do with orders-api and nothing else. A token for another API is a separate token; see Calling your API. The scope a token was granted does not change its roles or permissions. The full list of claims is in Tokens and claims.
{ "aud": "orders-api", "sub": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10", "acr": "aal2", "roles": ["editor"], "permissions": ["orders:read", "orders:write"]}Checking them in your backend
Section titled “Checking them in your backend”Verify the token first (see Protect an API), then check the claims. With the Rust SDK, AuthUser has the checks built in:
use auth_client::{AuthError, AuthUser};
async fn ship_order(user: AuthUser) -> Result<&'static str, AuthError> { user.require_permission("orders:write")?; // 403 insufficient_permission otherwise Ok("shipped")}
async fn admin_report(user: AuthUser) -> Result<String, AuthError> { user.require_role("admin")?; user.require_aal2()?; // 401 insufficient_user_authentication: ask for a second factor Ok(format!("report for {}", user.id()))}has_permission(name) and has_role(name) answer bool for code that decides rather than refuses. is_machine() tells a machine client’s token from a user’s. In any other language, read the roles and permissions arrays of the verified token.
Check permissions rather than roles where you can: a permission is what the code needs, and roles can then be reshaped in the dashboard without a deploy.
Who may change what
Section titled “Who may change what”Granting power takes the admin role in the workspace: giving roles to users, setting a machine client’s roles, creating a role with permissions, and changing a role. Developers may create APIs, permissions and empty roles, and delete them. See the roles of a workspace.