Session Lifecycle

Session states, browser binding, locked-session recovery, token refresh, and logout behavior.

Endpoint schemas live in the API Reference. This page covers shared session behavior: pending, locked, and unlocked sessions; browser binding; token refresh; and logout.

Session States

A session can be in one of three states. Each state has a distinct server-side shape, a distinct TTL, and a distinct way out.

Loading diagram…

Session lifecycle summary

Browser login starts in pending and binds into unlocked. From unlocked, refreshing without owner_token and user_member_token drops the session into locked. A locked session is authenticated but document and membership operations return 401 SESSION_LOCKED; it can be restored to unlocked by POST /auth/recovery/tokens or by POST /auth/tokens/refresh with both crypto tokens. DELETE /sessions/current or DELETE /sessions ends an unlocked session. locked is also entered directly by POST /auth/recovery; unlocked is also created directly by programmatic POST /auth/tokens/refresh with both crypto tokens.

State	Created by	What the access token carries	TTL	Next transition
Pending	`POST /auth/opaque/authenticate-finish` (browser mode)	`pending: true` flag, `revocationTokenHash` — no DB session yet.	60 seconds	`POST /auth/session/bind`
Locked	`POST /auth/recovery` (always); `POST /auth/tokens/refresh` (when called without `owner_token` and `user_member_token`)	Access token entry without `owner_token` and `user_member_token`.	Standard 15 minutes	`POST /auth/recovery/tokens` (recovery flow) or `POST /auth/tokens/refresh` with `owner_token` + `user_member_token`
Unlocked	`POST /auth/tokens/refresh` with `owner_token` + `user_member_token`; `POST /auth/session/bind` (browser); `POST /auth/recovery/tokens` (recovery)	Access token entry plus `owner_token` and `user_member_token`.	Standard 15 minutes	`DELETE /sessions/current` (single session) or `DELETE /sessions` (all sessions)

owner_token and user_member_token are derived client-side from personal key material. Literal cannot compute them. Without them, a session can authenticate but cannot access document or membership operations.

Browser Session Binding

Browser clients avoid receiving the refresh token directly in the login response. Instead, the client derives the refresh token locally through OPRF evaluation and binds the session so the server can set an HttpOnly refresh cookie.

Pending access tokens are accepted only by POST /auth/session/refresh-eval and POST /auth/session/bind. Any other request returns 401.

Step 1 — Receive The Pending Access Token

POST /auth/opaque/authenticate-finish returns a pending access token with a 60-second TTL.

Step 2 — Evaluate The OPRF

The client submits a blinded ristretto255 point. Literal multiplies it by its OPRF key scalar and returns the evaluated point. The server never learns the client’s refresh secret; the client never learns the OPRF key. The client unblinds the result locally to derive the 32-byte refresh token.

Endpoint: POST /auth/session/refresh-eval

Step 3 — Bind The Session

The client submits the derived refresh token to bind the session. Literal validates the pending entry, retires the pending state, creates a DB session row keyed by SHA-256(refresh_token), and issues a full access token with a 15-minute TTL. In browser mode, the response also sets the literal_rt HttpOnly cookie carrying the refresh token; programmatic clients receive the refresh token in the response body.

Endpoint: POST /auth/session/bind

After bind, Literal holds only the SHA-256 of the refresh token, never the token itself.

Locked Sessions

There are two paths to a locked session, each with its own unlock procedure.

After Account Recovery

Recovery returns a locked session because key material and BIK-derived tokens have changed. The client must derive new session tokens and submit token rotations before document operations are available.

Endpoint: POST /auth/recovery/tokens

Use the API Reference for exact request fields.

After Refresh Without Crypto Tokens

If refresh is called without owner_token and user_member_token, the new session is locked. Refresh again with both tokens to restore document and membership access.

Endpoint: POST /auth/tokens/refresh

Token Rotation After Recovery

Recovery changes key material, so affected owner, grantor, document, and membership tokens must be rotated. The client submits old-to-new token mappings so Literal can update stored opaque tokens without learning the plaintext identifiers behind them.

See Blind Routing for the broader token-rotation model and Account Recovery for the recovery workflow.

Endpoints That Require An Unlocked Session

Requests to these endpoints with a locked session return 401 with error code SESSION_LOCKED.

Domain	Affected endpoints
Documents	Create, list, reservations, OCR result, consumer indexes
Entities	List, add member, manage members
Deliveries	Discover, received, reserve, create, lifecycle
Search	Document search
Jobs	Get job status

All auth, token refresh, and public endpoints accept locked sessions.

Ending A Session

Both logout routes require a valid access token and return 204 No Content on success. The literal_rt cookie is cleared automatically for browser clients.

Endpoint	Scope
`DELETE /sessions/current`	Current session.
`DELETE /sessions`	All sessions; requires the client-derived revocation token.

The revocation token is issued during login alongside the access and refresh tokens. It authorizes bulk invalidation of every session tied to the account. Store it alongside the refresh token — if it is lost, all-session logout is unavailable until the next login.