Get my session state
Returns the current state of the current session including its factors and all currently satisfied assurance levels. `assurance_levels[]` may shrink over time as factor freshness windows expire, without the session itself expiring. Use step-up authentication (a new `auth_attempt` against the same `session_id`) to restore a dropped assurance level.
Returns the current state of the current session including its factors and all currently satisfied assurance levels.
assurance_levels[] may shrink over time as factor freshness windows expire,
without the session itself expiring. Use step-up authentication (a new auth_attempt
against the same session_id) to restore a dropped assurance level.
Authorization
nextgenSession The __nextgen_session cookie issued at session creation or superseding handoff exchange.
A missing or invalid cookie yields 401 with code auth.unauthorized and the message
Missing or invalid session token.
In: cookie
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/sessions/me"{ "session_id": "abc123def456", "project_id": "river-8421", "state": "active", "user_id": "user_id_12345", "factors": [ { "method": "password", "verified_at": "2026-04-28T15:32:00Z", "payload": { "user_id": "user_id_12345" } } ], "assurance_levels": [ "urn:nist:aal:1", "urn:nist:aal:2" ], "metadata": {}, "user_agent": { "fingerprint": "fp_abc123", "ip": "203.0.113.42" }, "created_at": "2026-04-29T10:00:00Z", "expires_at": "2026-04-30T10:00:00Z"}{ "code": "string", "message": "string", "details": {}}{ "code": "string", "message": "string", "details": {}}{ "code": "string", "message": "string", "details": {}}Exchange handoff token for a session POST
Consumes a one-time `handoff_token` minted by `POST /auth_attempts/{id}/handoff` and returns the resulting session and a `session_token`. The server resolves the originating `auth_attempt` from the token and then: | Originating auth_attempt | Outcome | |---|---| | No `session_id` | A new authenticated session is **created**. | | `session_id` points to an anonymous shell | Existing session is **upgraded** — user and factors written in, TTL reset to full session TTL. | | `session_id` points to an active session (step-up) | Existing session is **upgraded** — new factors merged, `assurance_levels[]` expanded. | The response shape is identical in all three cases. The `session_token` supersedes any previously issued `session_token` for the same session. Clients must replace their stored token at this point. Requires a project service key (OAuth2 client credentials).
Get session state GET
Returns the current state of a session including its factors and all currently satisfied assurance levels. `assurance_levels[]` may shrink over time as factor freshness windows expire, without the session itself expiring. Use step-up authentication (a new `auth_attempt` against the same `session_id`) to restore a dropped assurance level.