Sessions
OpenAPI operations for session creation, lookup, exchange, and teardown.
Sessions represent authenticated and anonymous runtime state. Use these endpoints to create shells, exchange handoff tokens, inspect sessions, list project sessions, and revoke sessions.
Complete authentication and create handoff token POST
Completes the authentication attempt and mints a `handoff_token`. Call this after all required factors have been verified and the attempt is in `completed` state. The handoff token is short-lived (≤60 seconds) and must be exchanged at POST /sessions/exchange to receive the final session and session_token. The handoff token is: - Single-use (atomic exchange, no retry) - Audience-bound (requires matching project key for exchange) - Idempotency-safe within a 5-minute window (see conventions)
Create an anonymous session shell POST
Creates an anonymous session shell with no user and no factors (`state: building`). This is optional — an `auth_attempt` will create a session implicitly if none is provided. Use this explicitly when you want to: - Pre-allocate a `session_id` before the user is known, so device/telemetry signals can be correlated with the eventual authenticated session from the start. - Track anonymous state (bot detection, device fingerprint) that survives until authentication. The returned `session_token` authorises GET and DELETE on this session. It is superseded when a handoff exchange completes — clients must replace it at that point. Anonymous sessions expire aggressively (10-minute TTL). The TTL resets to the configured full session TTL when the first authentication factor is written via a completing `auth_attempt`.