Sessions and lifetimes
A session is one login: made when someone proves who they are, renewed whenever an app refreshes its tokens, and over when it is ended or runs out. See Sessions and sign-out.
Ending a session ends its refresh tokens at once. An access token cannot be taken back: an API learns of the end when the token it holds expires.
Sessions
Section titled “Sessions”The session object:
| Field | Type | Meaning |
|---|---|---|
id |
uuid | The sid of its tokens. |
user |
object | { id, email, name } |
aal |
integer | 1 for one factor, 2 with two steps. |
amr |
string[] | How the user proved who they are, such as ["email"]. |
auth_time |
string | When they last did. |
ip, country, user_agent |
string | Where the login came from. |
device, browser, os |
string | What the user agent names, such as mobile, Safari, iOS. |
hosted |
boolean | Whether it was made on the hosted login page. |
created_at, last_seen_at, expires_at |
string | expires_at is the nearer of the two ends. |
ends |
string | Which limit ends it first: idle (unused for too long) or max (the longest a session may last). |
latest_end |
string | The latest the session can end. |
apps[] |
array | { id, name } of the apps that hold a refresh token from it. |
List sessions
Section titled “List sessions”The sessions that are good now, most recently used first.
| Query | Meaning |
|---|---|
query |
Part of an email address, a name or an IP address. |
user |
One user’s id. |
before |
A last_seen_at: the page after it. |
limit |
25 by default, at most 100. |
{ "sessions": [ { "id": "…", "aal": 1, "amr": ["email"], "country": "DE", "device": "mobile", "browser": "Safari", "os": "iOS", "hosted": false, "ends": "idle", "…": "…" } ], "next_before": null, "summary": { "sessions": 3, "users": 2, "recent": 3, "recent_hours": 24, "strong": 0 }}summary is the environment’s counts, as the dashboard’s Sessions page shows them.
Read a session
Section titled “Read a session”The session object plus its tokens:
{ "tokens": [ { "client_id": "your-app-spa", "client_name": "Your App", "client_type": "spa", "app": { "id": "…", "name": "Your App" }, "audience": "account", "scope": "openid profile email offline_access", "dpop": true, "renewed_at": "…", "expires_at": "…" } ]}A session that has ended answers 404.
End a session
Section titled “End a session”Answers 204, or 404 once it has ended. Sends session.revoked to your webhooks.
End every session
Section titled “End every session”Signs everybody out of the environment. The group’s slug must be repeated in confirm. Logins that were under way when it was done end too: a login begun before it is answered invalid_session at its next step and starts again.
POST /v1/environments/{env}/sessions/revoke-all{ "confirm": "your-app" }
200{ "revoked": 2 }Any other confirm answers 400 “confirm must repeat the slug of the environment’s apps: this signs everybody out”.
Lifetimes
Section titled “Lifetimes”How long tokens and sessions last is the environment’s own setting. See the lifetimes reference for what each one means.
Read the lifetimes
Section titled “Read the lifetimes”{ "lifetimes": { "access_token": 300, "id_token": 300, "machine_token": 300, "refresh_token": 2592000, "session_idle": 2592000, "session_max": 7776000 }, "defaults": { "access_token": 300, "id_token": 300, "machine_token": 300, "refresh_token": 2592000, "session_idle": 2592000, "session_max": 7776000 }, "limits": { "access_token": { "min": 60, "max": 86400 }, "…": "…" }}Change the lifetimes
Section titled “Change the lifetimes”All six, in seconds:
| Field | Default | Min | Max |
|---|---|---|---|
access_token |
300 (5 minutes) | 60 (1 minute) | 86400 (1 day) |
id_token |
300 | 60 | 86400 |
machine_token |
300 | 120 (2 minutes) | 86400 |
refresh_token (unused) |
2592000 (30 days) | 300 (5 minutes) | 31536000 (365 days) |
session_idle |
2592000 (30 days) | 300 | 31536000 |
session_max |
7776000 (90 days) | 300 | 31536000 |
The set must also hold together: session_idle no longer than session_max, and access_token no longer than session_idle or refresh_token, because a session is seen in use only when a token is renewed. A value out of bounds answers 400, such as “the access token lifetime must be between 1 minute and 1 day”.
Tokens issued from then on get the new lifetimes. A shorter limit on sessions also holds for the sessions that exist, from the moment it is saved; a longer one reaches a session the next time it is used. The answer is the same as the read, plus shortened, the number of sessions given a nearer end.