Tokens and claims
A login gives a client up to three tokens: an access token for one API, an ID token that says who logged in, and a refresh token to renew them. Their lifetimes are the environment’s; see Lifetimes.
Access tokens
Section titled “Access tokens”A JWT signed with the environment’s ES256 key (RFC 9068), for exactly one audience. APIs verify it offline against the key set; see Calling your API.
{ "alg": "ES256", "typ": "at+jwt", "kid": "3f0c9a51e2b84d6f9a7c1e5b2d8f4a60" }Check typ: an ID token is signed with the same key, and an API must not take one in place of an access token.
| Claim | User’s token | Machine client’s token |
|---|---|---|
iss |
The issuer. | The issuer. |
sub |
The user’s id (a UUID), stable within the environment. | The client’s client_id. |
aud |
One string: the API’s audience, account by default. |
The API’s audience. |
client_id |
The client the token was issued to. | The client. |
sid |
The session’s id. | "" |
jti |
A unique id. | A unique id. |
iat, exp |
Issued at, and expiry: iat plus the access token lifetime. |
iat plus the machine token lifetime. |
scope |
The granted scope. | "" |
auth_time |
When the user last proved who they are. | Equal to iat. |
acr |
aal1, or aal2 after a second factor or a passkey. |
client |
amr |
How the session was proven; see below. | [] |
roles |
Role names; see below. | The client’s role names. |
permissions |
Permission names of this audience. | The same, from the client’s roles. |
cnf |
{ "jkt": "<key thumbprint>" } on a DPoP-bound token; absent otherwise. |
Never: machine tokens are not bound. |
There is no claim for the workspace, the group or the app: the issuer says which environment, and aud which API.
{ "iss": "https://your-app.auth.dev.seek.services", "sub": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10", "aud": "orders-api", "client_id": "your-app-spa", "sid": "5d2c8e0a-7b1f-4a3e-9c6d-2e4f8a0b1c3d", "jti": "a1b2c3d4-…", "iat": 1791460990, "exp": 1791461290, "scope": "openid profile email offline_access", "auth_time": 1791460980, "acr": "aal2", "amr": ["email", "otp"], "roles": ["editor"], "permissions": ["orders:read", "orders:write"], "cnf": { "jkt": "0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I" }}A token from the client credentials grant can be told from a user’s by its empty sid (the Rust SDK’s AuthUser::is_machine()), or by acr: "client".
Roles and permissions
Section titled “Roles and permissions”Both are computed when the token is issued, for its audience:
rolesholds the user’s group-wide roles and their roles of the app that owns the audience. Roles of the group’s other apps are left out.permissionsis the union of those roles’ permissions on this audience only.- A role marked “requires two-step login” counts only in a session at
aal2; in anaal1session it is silently left out of the token. It never counts for a machine client.
Scopes do not change roles or permissions. A change to a user’s roles reaches their tokens at the next refresh, so within one access token lifetime. See Roles and permissions.
ID tokens
Section titled “ID tokens”Issued with the openid scope, to the client itself (aud is the client_id). Signed ES256, or RS256 when the client was registered with id_token_alg: "RS256". Header: { "alg": "ES256", "typ": "JWT", "kid": "…" }.
| Claim | Meaning |
|---|---|
iss, sub, aud, iat, exp |
As usual; exp is iat plus the ID token lifetime. |
auth_time |
When the user last proved who they are. |
nonce |
The request’s nonce, on the ID token of the code exchange only (a refresh’s ID token has none). |
acr, amr, sid |
As in the access token. |
at_hash |
The left half of the SHA-256 of the access token, base64url. |
| profile claims | By scope; see scopes. |
Refresh tokens
Section titled “Refresh tokens”Opaque strings of 43 characters, issued with the offline_access scope. SeekAuth keeps only their SHA-256 hash.
- Rotated: every use returns a new one and uses up the old one. There is no grace window.
- Reuse ends the session: an old one presented again revokes its whole family and the session. See /token.
- Bound: a public client’s refresh token works only with a DPoP proof from the key it was issued to.
- Never outlives its session: each one expires at the sooner of the refresh token lifetime and the session’s end.
refresh_expires_inin the token response says when.
Scopes
Section titled “Scopes”| Scope | Gives |
|---|---|
openid |
An ID token, and access to /userinfo. |
profile |
name and picture, when the user has them. |
email |
email and email_verified, when the user has an address. |
phone |
phone_number and phone_number_verified, when the user has a number. Logging in with a phone number is not available yet, so users have none for now. |
offline_access |
A refresh token. |
Other scopes are dropped from the request. The SDKs ask for openid profile email offline_access.
acr and amr
Section titled “acr and amr”acr is the level of the login:
acr |
Meaning |
|---|---|
aal1 |
One factor. |
aal2 |
Two factors, or a passkey, which counts as both. |
client |
A machine client’s token: no user. |
amr lists how the session was proven, from these values:
amr |
Factor |
|---|---|
email |
A code sent by email. |
pwd |
A password. |
otp |
An authenticator app code. |
recovery |
A recovery code. |
passkey |
A passkey. |
wallet |
A Solana or EVM wallet signature. |
social |
Any social or custom provider. |