ZitadelDocs

Create an anonymous session shell

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. Creating a session is an app-plane operation on the project credential (`session.write`). The returned `session_token` is a session credential for the end-user client, not a management scope: it is delivered as the `__nextgen_session` cookie and authorises the self-service operations `GET /sessions/me` and `DELETE /sessions/me` (`nextgenSession` scheme). The by-id operations `GET /sessions/{session_id}` and `DELETE /sessions/{session_id}` are operator endpoints and require `session.read` / `session.delete` instead. The `session_token` 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`.

POST
/sessions

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.

Creating a session is an app-plane operation on the project credential (session.write). The returned session_token is a session credential for the end-user client, not a management scope: it is delivered as the __nextgen_session cookie and authorises the self-service operations GET /sessions/me and DELETE /sessions/me (nextgenSession scheme). The by-id operations GET /sessions/{session_id} and DELETE /sessions/{session_id} are operator endpoints and require session.read / session.delete instead.

The session_token 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.

Authorization

oauth2 session.write
headerAuthorizationBearer <token>

Scope: session.write

Request Body

application/json
  1. body

Request to create an anonymous session shell.

project_id*project-id
Match^[a-zA-Z0-9_-]+$
user_agent?

Optional user agent / device context to attach to the session. Useful for correlating telemetry and device signals with the eventual authenticated session from the start.

Response Body

Anonymous session created successfully.

application/json
  1. response

Response for session creation and handoff exchange. Includes the session state and the session_token required to manage it.

session*

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_token*string

Bearer token authorising management of this session (GET and DELETE). For anonymous sessions this token is superseded when a handoff exchange completes — clients must replace their stored token at that point.

curl -X POST 'https://example.com/sessions' \  -H 'Content-Type: application/json' \  -d '{  "project_id": "string"}'
{  "session": {    "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"  },  "session_token": "string"}