Skip to content

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.

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.

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.

How an app signs a user out depends on how they logged in.

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.

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:

  • 204 for a login made in the modal, which is then over;
  • 200 with { "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.

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”:

GET/account/v1/sessionsthe user
DELETE/account/v1/sessions/:idthe user; fresh login for another session

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).

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.

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.