Sessions and tokens

How a session differs from a token, which tokens an application receives, what each contains, and how long each lives.

On this page

A session is identity's record that a browser is signed in. A token is what an application receives so it can act for that person. They are separate things. A session lives on identity and a token lives with an application. Ending a session ends the refreshing of the tokens that came from it.

	Session	Token
Held by	Identity, referenced by a cookie in the browser.	The application.
Used for	Letting you through identity's own pages.	Telling an application who you are, and letting it call an API.
Seen by applications	No.	Yes.
Ends when	You sign out, it goes idle, or it reaches its absolute limit.	It expires, or the session behind it ends and it can no longer be refreshed.

See Sessions for the first column.

The three tokens#

After a sign-in an application can receive three tokens. It collects them at the token endpoint, /token, in exchange for the authorization code.

Token	What it is for	Form
ID token	Tells the application who signed in and how.	A signed JWT.
Access token	Presented by the application to an API.	A signed JWT of type `at+jwt` (RFC 9068).
Refresh token	Gets a new access token without another sign-in.	An opaque value. Identity stores only a hash of it.

The ID token#

The ID token is for the application that asked for the sign-in, and for nobody else. Its audience is that application's client id. It says who you are and how you proved it. It is not a credential to call an API with.

Claim	Meaning
`sub`	Your account identifier. The same in every application, except one registered for per-application identifiers, which sees an identifier of its own for you.
`iss`, `aud`, `iat`, `exp`	Who issued it, who it is for, and when it was issued and expires.
`auth_time`	When you signed in. Not moved by a step-up, and not made newer by switching organization in the account area.
`acr`, `amr`	The assurance level and the methods used.
`sid`	The session it came from.
`nonce`	Echoes the value the application sent, to tie the token to its request.
`tid`, `tslug`	The organization, whenever the authorization belongs to one.
Profile claims	The name, picture, locale and so on, only for the `profile` scope, and the email address and `email_verified`, only for the `email` scope.

An ID token's life is the same as the client's access-token lifetime. An application must verify it: the signature, the issuer, the audience, the nonce and the expiry. The SDK does this for you. See Log users in.

The access token#

The access token is the one an API sees. It is bound to a key the application holds, using DPoP (RFC 9449), for every client except a first-party web client. A stolen bound token is useless without the key.

Claim	Meaning
`sub`	Your account identifier. Always your real identifier, even for an application registered for per-application identifiers.
`aud`	Exactly one audience.
`client_id`, `azp`	The client the token was issued to.
`scope`	The scopes granted, separated by spaces.
`tid`, `tslug`	The organization, whenever the authorization belongs to one.
`sid`	The session.
`acr`, `amr`, `auth_time`	How and when you signed in.
`cnf`	The key the token is bound to.
`act`	Present on a delegated token: who is acting for you. See Delegation and token exchange.
`av`, `rv`	Version numbers used to tell that a token has gone out of date: `av` for your account's authorization, and `rv` for the organization's resources, present only with `tid`.
`kind`	The kind of principal.
`jti`, `iat`, `nbf`, `exp`	Identifier, issue time, not-before and expiry.

It carries no roles claim. What you may do is decided by asking identity, not by reading the token. See Authorization.

A token that came from a service credential or from an exchange has no sid, acr, amr or auth_time, because no person signed in at that moment.

The refresh token#

A refresh token is only issued when the client may use refresh tokens and the application asked for the offline_access scope. Each use of a refresh token returns a new one and retires the old one, which is covered on Token families and refresh rotation.

How long each lives#

Item	Lifetime	Configurable
Pushed authorization request reference	60 seconds, single use	An operator can shorten it, not lengthen it
Authorization code	60 seconds, single use	An operator can shorten it, not lengthen it
Access token	At most 900 seconds (15 minutes). A newly registered client gets 600 seconds unless registered with another value.	Per client, up to the 900-second ceiling; an operator can lower the ceiling
ID token	The same as the client's access-token lifetime	Per client
Access token from `client_credentials`	900 seconds, no refresh token	No
Refresh token, third-party client	At most 7 days sliding and 30 days absolute	A client's registered value may be shorter, never longer; an operator can shorten both windows
Refresh token, first-party client	The client's registered lifetime. A newly registered client gets 30 days.	Per client

A refresh token's absolute expiry never goes past the session's absolute limit, and a refresh is refused once the session has ended. An authorization code that is redeemed twice revokes the tokens the first redemption created.

What an API should do with a token#

Check the signature, iss, exp and that aud is itself, and the DPoP proof where the token is bound.
Read scope for what the application was allowed, and ask identity for what the person may do.
Not treat an access token as proof of the current state. It can be minutes old. An API that must react sooner can ask identity whether the person still has access.

The developer steps are in Protect your API.