Skip to content

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.

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.
GET/v1/environments/:id/sessionsviewer

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": "…",
"user": { "id": "…", "email": "[email protected]", "name": "Ada" },
"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.

GET/v1/environments/:id/sessions/:sessionviewer

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.

DELETE/v1/environments/:id/sessions/:sessiondeveloper

Answers 204, or 404 once it has ended. Sends session.revoked to your webhooks.

POST/v1/environments/:id/sessions/revoke-alladmin

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

How long tokens and sessions last is the environment’s own setting. See the lifetimes reference for what each one means.

GET/v1/environments/:id/lifetimesviewer
{
"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 }, "…": "…" }
}
PUT/v1/environments/:id/lifetimesadmin

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.