Sessions and sign-out
A session is a login. It is made when someone proves who they are, used again whenever one of their apps renews its tokens (or the hosted login page answers from its cookie), and over when it is ended or runs out. Every token an app holds comes from a session: when the session ends, its refresh tokens stop working, and its access tokens run out within minutes.
Sessions belong to the environment, so the apps of a group see the same ones. The Sessions page of the dashboard lists who is signed in, on what, with which apps, and what ends each session first.
How long things last
Section titled “How long things last”Each environment sets its own lifetimes, on the Sessions page (the Lifetimes tab) or with PUT /v1/environments/:id/lifetimes (admin role). Out of the box:
| Default | |
|---|---|
| Access token, ID token, machine client’s token | 5 minutes |
| Refresh token, unused | 30 days |
| Session, unused (inactivity timeout) | 30 days |
| Session, at most | 90 days |
A session is seen in use when an app renews a token, and each use moves its inactivity timeout on, never past its maximum. A refresh token never outlives its session. The limits and the rules between them are in Lifetimes.
A shorter limit holds for the sessions that already exist from the moment it is saved: a session that is now over the new limit has ended. A longer limit reaches a session the next time it is used. Tokens already issued keep the lifetime they were issued with.
Refresh tokens rotate
Section titled “Refresh tokens rotate”Every refresh returns a new refresh token and uses the old one up. A refresh token that is presented a second time is taken as stolen: SeekAuth ends the session it belongs to with every token of it, records refresh.reuse_detected, and emails the user. There is no grace window, so a client must never send the same refresh token twice, even from two tabs at once. The browser SDK runs one refresh at a time across tabs for this reason, and the Rust WebClient refreshes under a lock on the session’s row. See Tokens and sessions.
Signing out
Section titled “Signing out”How an app signs a user out depends on how they logged in.
A single-page app
Section titled “A single-page app”logout() from auth-react (or auth-js) forgets the tokens in the browser and revokes the refresh token at /revoke. For a login made in the embedded login (the modal), revoking the refresh token ends the whole session, with its tokens.
const { logout } = useAuthStore()// <button onClick={logout}>Log out</button>A login made on the hosted page also left a cookie on the issuer’s host, so other apps of the group could answer from it. For such a session, logout() then sends the browser to the issuer’s /logout with the ID token as id_token_hint, and back to postLogoutRedirectUri, which must be one of the client’s post-logout redirect URIs (in development any http://localhost address also works). The cookie’s session ends, the cookie is cleared, and the browser returns.
/logout asks “Log out?” first when it cannot tell the request came from the session itself. With an id_token_hint of the browser’s own session it does not ask. It only ever ends the session the browser’s cookie proves, never one named in a link.
A web client
Section titled “A web client”With a backend that holds the tokens (auth-client’s WebClient), logout() from auth-react posts to the backend’s /auth/logout. The backend clears its session cookie and answers:
204for a login made in the modal, which is then over;200with{ "end_session_url": "…" }for a login made on the hosted page; auth-react then sends the browser there, which ends the issuer’s session as above and comes back to the page’s origin. Register that origin as one of the client’s post-logout redirect URIs, or the browser stays on the issuer’s “Logged out” page.
A backend that renders pages without script uses logout_redirect(&headers, back) in a route of its own, with a back address the backend chooses, never one read from the request.
Signing a user out everywhere
Section titled “Signing a user out everywhere”By the user
Section titled “By the user”The account API lists the user’s own sessions and ends any of them, so an app’s settings page can offer “sign out of this device”:
Ending the session the token comes from is a logout. Ending another one needs a fresh login, so wrap it in withStepUp like the other changes: a session left signed in somewhere cannot log the account’s owner out.
Changing the password or the email address through the account API ends every other session of the user too, and keeps the one that made the change. So does turning on two-step login (the first authenticator app or passkey).
By an admin
Section titled “By an admin”| What | Dashboard | API | Role |
|---|---|---|---|
| End one session | Sessions, the session’s drawer | DELETE /v1/environments/:id/sessions/:session |
developer |
| End all of one user’s sessions | Users, the user’s page | POST /v1/environments/:id/users/:user/revoke-sessions |
developer |
| Disable a user (ends every session) | Users | PATCH /v1/environments/:id/users/:user with { "status": "disabled" } |
developer |
| End every session of the environment | Sessions | POST /v1/environments/:id/sessions/revoke-all with the group’s slug in confirm |
admin |
Ending every session signs everybody out of every app of the group, so the API wants the group’s slug repeated in the body, { "confirm": "your-app" }, and answers how many sessions it ended, { "revoked": 42 }. It takes the admin role, which an API key does not have (keys act as developers), so it is done in the dashboard or by an admin’s own session. See Sessions and lifetimes.
What reaches your API, and when
Section titled “What reaches your API, and when”An access token cannot be taken back: it is valid until it expires, five minutes by default. A session that ends reaches an API when the access tokens it gave out run out, and the next refresh is refused with invalid_grant. /userinfo and introspection check the session at once, for a backend that must know sooner. Keep the access token lifetime short if this window matters to you.
A web client’s backend keeps a session of its own, in its database. It ends when a refresh is refused with invalid_grant. To end it at once when a user is deleted or disabled, listen for the user.deleted and user.disabled webhooks and call end_sessions_of(user_id); end_all_sessions() ends every session of the client.