Skip to content

Lifetimes

How long tokens and logins last is a setting of each environment, changed on the Sessions page of the dashboard (the Lifetimes tab) or with PUT /v1/environments/:id/lifetimes, which takes the admin role.

Lifetime Field Default Shortest Longest
Access token access_token 5 minutes 1 minute 1 day
ID token id_token 5 minutes 1 minute 1 day
Machine client’s token machine_token 5 minutes 2 minutes 1 day
Refresh token, unused refresh_token 30 days 5 minutes 365 days
Session, inactive session_idle 30 days 5 minutes 365 days
Session, at most session_max 90 days 5 minutes 365 days

The API takes and answers them in seconds (300, 2592000, 7776000 for the defaults). Out of the box: an access token lasts five minutes and is renewed without the user noticing, a login ends after 30 days nobody used it, and after 90 days in any case.

A set is accepted only when:

  • each lifetime is within its limits;
  • the inactivity timeout is not longer than the maximum;
  • the access token does not last longer than the inactivity timeout, or than the refresh token. A session is seen in use only when its tokens are renewed, so an access token that outlived the inactivity timeout would let a session look idle while it is used.
  • A session ends at the sooner of its last use plus session_idle and its start plus session_max. Every refresh of a token from it, and every answer from the hosted page’s cookie, counts as use.
  • A refresh token expires at the sooner of its issue plus refresh_token and its session’s end. It never outlives its session. The token response says how long it has left in refresh_expires_in, which a backend can use to end its own session record at the same time; the Rust SDK’s web client does.
  • Access and ID tokens last their lifetime from issue. An access token cannot be taken back, so an API that verifies it offline accepts it until it expires, even after its session ended. That is why it is short.

Tokens issued after a change get the new lifetimes; tokens already issued keep theirs.

A shorter session or refresh token limit holds for the logins that exist too, from the moment it is saved: every check of a session measures it against the environment’s limits as they are now. The answer of the change says how many sessions were given a nearer end (shortened). A longer limit reaches a session the next time it is used.

These are not settings:

What Lasts
Authorization code 60 seconds, one use.
Session ticket 60 seconds, one use.
A login attempt on the hosted page 15 minutes.
The “Continue as …?” question’s cookie 120 seconds.
A code sent by email 10 minutes.
Setting up an authenticator app or a passkey 10 minutes from the start.
Linking a provider 10 minutes from the start.
A fresh login, for the account API 600 seconds after the user proved who they are.

See also Sessions and sign-out.