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.
The six lifetimes
Section titled “The six lifetimes”| 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.
How they apply
Section titled “How they apply”- A session ends at the sooner of its last use plus
session_idleand its start plussession_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_tokenand its session’s end. It never outlives its session. The token response says how long it has left inrefresh_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.
Changing them
Section titled “Changing them”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.
Fixed lifetimes
Section titled “Fixed lifetimes”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.