ZitadelDocs

Get session state

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.

GET
/sessions/{session_id}

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.

Authorization

oauth2 session.read
headerAuthorizationBearer <token>

Scope: session.read

Path Parameters

session_id*string

The unique identifier of the session.

Match^sess_[a-zA-Z0-9_-]+$

Response Body

Session state.

application/json
  1. response

The current state of a session.

A session is the durable post-auth primitive. It accumulates verified authentication factors and exposes assurance_levels[] — the set of assurance profiles its current factors satisfy. Sessions are read-only from the client's perspective: factors flow in through auth_attempts.

session_id*session-id

Unique identifier for this session (dialect-minted prefixed opaque string).

Match^sess_[a-zA-Z0-9_-]+$
project_id*project-id
Match^[a-zA-Z0-9_-]+$
state*string

Current lifecycle state of the session:

  • building: no verified authentication factors yet
  • active: has at least one verified authentication factor; assurance_levels[] may shrink as factors age
  • expired: TTL elapsed
Value in"building""active""expired"
user_id?|

The authenticated user. Null for anonymous sessions and until the user factor has been verified through an auth_attempt.

user?

The authenticated user's resolved reference, derived live from the user schema's x-identifier/x-display designations (ADR 058). Present on identity-hydrating reads (GET /sessions/me, session get and query) whenever the session has an authenticated user; absent for anonymous sessions. Clients render display, falling back to identifier, then user_id.

factors*array<>

Verified authentication factors accumulated by this session. Each key is a factor type (e.g. password, totp, passkey). Each value is a factor event object with at least verified_at and method-specific properties (e.g. user_verified, hardware for passkeys).

assurance_levels?array<string>

All assurance levels whose schemas the current session factors satisfy. This list shrinks as factor freshness windows expire and grows when step-up auth_attempts add or refresh factors. Whether any level is "enough" is determined by the request context, not the session.

metadata?|

Arbitrary key/value metadata attached to the session.

user_agent?|

User agent information captured at session creation.

created_at*string

When this session was created.

Formatdate-time
expires_at*string

When this session expires. Short TTL (10 min) for anonymous sessions; reset to the full configured session TTL once the first authentication factor is written.

Formatdate-time
curl -X GET 'https://example.com/sessions/string'
{  "session_id": "string",  "project_id": "string",  "state": "building",  "user_id": "string",  "user": {    "user_id": "string",    "identifier": "string",    "identifier_property": "string",    "display": "string"  },  "factors": [    {      "method": "identifier",      "verified_at": "2019-08-24T14:15:22Z",      "payload": {        "method": "identifier",        "user_id": "string"      }    }  ],  "assurance_levels": [    "string"  ],  "metadata": {},  "user_agent": {    "fingerprint": "string",    "ip": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z"}