Tokens and sessions
Access tokens are short and cannot be taken back
Section titled “Access tokens are short and cannot be taken back”An access token is a signed JWT that your API checks offline, so nothing can recall it once it is out: it works until it expires. That is why it lasts 5 minutes out of the box (an environment can set 1 minute to 1 day), and why ending a session reaches your API when the last token it gave out expires. See Lifetimes.
DPoP binds tokens to a device
Section titled “DPoP binds tokens to a device”A single-page app makes a key pair in the browser, which cannot be exported, and proves it holds the private key with every request. Its tokens carry the key’s thumbprint (cnf.jkt), and:
- a refresh token bound to a key is refused with any other key’s proof;
- an access token bound to a key is refused without a proof from that key, and refused when it is sent as a plain
Bearertoken; - each proof names the method and URL it is for, is fresh within minutes, and is accepted once.
A token copied out of the browser is therefore of no use elsewhere. Public clients must send DPoP proofs at /token; confidential clients may. See DPoP.
Refresh tokens rotate
Section titled “Refresh tokens rotate”A refresh token is an opaque value, stored as a hash. Each use returns a new one, and the one used is spent. The family of refresh tokens of one login lives at most as long as the session.
Refresh token reuse
Section titled “Refresh token reuse”There is no grace window: a spent refresh token presented again is taken as a sign that it was copied. SeekAuth then:
- revokes every refresh token of that family and every token of the session,
- ends the session,
- records
refresh.reuse_detectedandsession.revokedin the audit log, - emails the user, once per incident, that a login was ended to protect their account.
The answer is invalid_grant. A spent token keeps its original expiry so that the reuse is recognised even when it comes back days later. The SDKs never send one twice: they refresh one at a time, across tabs in the browser and under a row lock in WebClient.
The same applies to authorization codes: a code presented a second time revokes what was issued from it (code.reuse_detected).
Sessions end on time
Section titled “Sessions end on time”A session ends at the first of:
| Default | |
|---|---|
| No use (no token renewed, no login answered from the cookie) for the inactivity timeout | 30 days |
| Its maximum length, however much it is used | 90 days |
| A logout, or a revocation by the user or an admin |
A refresh token that rests unused for its own lifetime (30 days) stops working, and none outlives its session. A shorter limit saved for an environment applies to the sessions that already exist, from that moment.
Sessions that end on purpose
Section titled “Sessions that end on purpose”| Event | What ends |
|---|---|
| The user logs out | That session. |
| The user ends a session of theirs in account settings | That session. |
| The user changes their password or email address | Every other session of theirs. |
| The user turns on two-step login (a first authenticator app or passkey) | Every other session of theirs: they were signed in without a second step. |
| A password reset | Every session of the user. A user with a second step passes it before the new password is set. |
| An admin disables a user | Every session of the user. |
| An admin ends a session, or all of a user’s | Those. |
| An admin ends all sessions (with confirmation) | Every session of the environment. |
| A refresh token or code is reused | That session. |
Each of these also ends the logins that are under way for the user (or, when all sessions end, for everyone): a login that had passed its first step before the change cannot finish after it. So do the other changes to what guards an account: a second step added or removed, new recovery codes, a provider linked or unlinked.
Step-up
Section titled “Step-up”Sensitive changes ask for a recent login. The account API refuses changes to passwords, email addresses, second factors, linked providers and the account itself unless the user proved who they are in the last 10 minutes, with their second factor if they have one. Your own API can ask the same with require_aal2 and require_fresh. See Two-step login.