Session

Included from Basic tier

A session is one authenticated sign-in: established by a login through the ordered provider chain, kept alive by refresh-token rotation (a replayed predecessor revokes the whole session), and revoked by logout or an explicit per-session revoke. Access tokens are short-lived signed tokens; refresh tokens and api keys are opaque and hashed at rest. Refresh passes while the system is quiesced, login refuses. Served by the v2 AuthService: Login, Refresh, Logout, Introspect, ListSessions, RevokeSession, the api key verbs, the MFA factor verbs (ListFactors, EnrolTOTPFactor, ActivateTOTPFactor, RemoveFactor, Elevate, BeginIDPStepUp) and ChangePassword.

Session

Session is one session row.

Field	Type	Meaning
absolute_expires_at	timestamp	The session's absolute expiry — rotation never extends past it.
authn_method	string	The authn method the session was established with: "password" or "ldap" (provider instances such as "oidc:" join in later waves).
authn_strength	string	The session's authn strength: "none" until MFA lands, then "idp_asserted" | "totp" | "webauthn".
created_at	timestamp	When the record was created.
current	boolean	true when this is the session the request itself rode.
elevated_at	timestamp	When the session's step-up elevation window opened. Unset while the session has never elevated.
elevation_expires_at	timestamp	When the step-up elevation window closes.
id	string	The session's identity.
last_client_address	string	The client address of the session's latest refresh, resolved behind any trusted reverse proxy (server.trusted_proxies); equals source_address until the first refresh.
last_seen_at	timestamp	When the session last carried a request.
refresh_expires_at	timestamp	When the current refresh token expires (idle expiry; rotation renews it).
source_address	string	The client address the session was established from, resolved behind any trusted reverse proxy — history, never rewritten.
user_agent	string	The User-Agent the session was established with (first seen, never rewritten; bounded to 512 characters). With the credential kind, the device signal the platform records — enough for a user to recognise their own sessions, by design no fingerprinting.
user_id	string	The user the session belongs to.

SessionTokens

SessionTokens are the credentials a login or refresh mints.

Field	Type	Meaning
access_expires_at	timestamp	When the access token expires.
access_token	string	The signed access token (aud "api", 15-minute default TTL).
refresh_expires_at	timestamp	When the minted refresh token expires (rotation renews it, never past the session's absolute expiry).
refresh_token	string	The opaque rotating refresh token. Empty when it rode the Set-Cookie channel instead, and absent for contained break-glass sessions (the fire door is one bounded, re-authenticated session).

MFAFactor

MFAFactor is one factor-registry row. The secret never rides this message.

Field	Type	Meaning
activated_at	timestamp	When verify-to-activate enrolment finished and the factor became usable.
active	boolean	true once verify-to-activate enrolment finished; a pending factor authenticates nothing.
created_at	timestamp	When the record was created.
id	string	The record's identity.
kind	string	The factor kind: "totp" (the kind set is open — "webauthn" is the fast-follow on this same registry).
label	string	An optional caller-chosen display label.
last_used_at	timestamp	When the factor last verified a proof; unset when never used.

BeginIDPStepUpRequest

BeginIDPStepUp starts the identity-provider step-up round trip for the session the caller's own access token rode: that session id — never one named by a link — is sealed into the round trip's state together with its nonce, PKCE verifier and return path, the trip is bound to the calling browser through the login-binding cookie the response sets, and the callback elevates that session after validating the fresh id_token. Refused failed_precondition for a sessionless credential, a session that is not live, or a provider instance that elevates with a platform factor (Elevate); not_found on a server without federated sign-in.

Field	Type	Meaning
return_to	string	Where the browser lands once the session is elevated: a same-origin absolute path (query and fragment kept); anything scheme-, host- or control-character-shaped falls back to /.

BeginIDPStepUpResponse

Field	Type	Meaning
authorize_url	string	The identity provider's authorization URL (prompt=login, max_age=0) to navigate the browser to. The response also sets the login-binding cookie the callback requires, so the navigation must happen in the browser that made the call.

What settings change this

• token.access_expiry — access-token lifetime in minutes (default 15), clamped to the session's absolute expiry.
• token.refresh_expiry — how far each refresh rotation extends the session's refresh token (default 7 days), clamped to the absolute expiry.
• token.session_absolute_expiry — the absolute session bound (default 30 days): rotation never extends a session past login time plus this.
• token.enable_cookies — whether a browser caller may receive its refresh token in the HttpOnly opschain_refresh cookie instead of the response body.
• server.trusted_proxies (opschain docs config) — which peers' forwarding headers decide the recorded source_address and last_client_address; unset, the TCP peer is recorded.

Related pages

• opschain docs identity — the component page: the credential chain, providers and MFA.
• opschain docs resources/user — the account a session belongs to.
• opschain docs settings-reference — the full token/session tunable catalog.