Skip to content

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.

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.

Header
{ "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.

Claims of a user's access token
{
"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".

Both are computed when the token is issued, for its audience:

  • roles holds 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.
  • permissions is 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 an aal1 session 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.

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.

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_in in the token response says when.
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 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.