Zitadel Preview Docs
API referenceSessions

List sessions

Returns a paginated list of sessions for a project. Requires a project service key (OAuth2 client credentials).

GET
/sessions

Returns a paginated list of sessions for a project. Requires a project service key (OAuth2 client credentials).

Authorization

oauth2 sessions.read
AuthorizationBearer <token>

In: header

Scope: sessions.read

Query Parameters

limit?integer

Maximum number of items to return.

page_token?string

Token for fetching the next page of results. Obtain this value from next_page_token in the previous response. Omit to start from the beginning. Its format is opaque and may change between releases.

project_id*string

Filter sessions by project.

state?string

Filter sessions by lifecycle state.

user_id?string

Filter sessions by user.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/sessions?project_id=river-8421"
{  "sessions": [    {      "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"    }  ],  "next_page_token": "v1.dGhpcyBpcyBvcGFxdWU.SflKxwRJSMeKKF2QT4fw"}
{  "code": "string",  "message": "string",  "details": {}}
{  "code": "string",  "message": "string",  "details": {}}
{  "code": "string",  "message": "string",  "details": {}}
{  "code": "string",  "message": "string",  "details": {}}

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.

Revoke my session DELETE

Revokes the session immediately (`state: revoked`). This is the logout operation. The __nextgen_session cookie issued at creation (or superseded by a handoff exchange) is required. After revocation, any tokens derived from this session are invalidated including the cookie itself, which is cleared in the response.