Zitadel Preview Docs

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
AuthorizationBearer <token>

In: header

Scope: session.write

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create an anonymous session shell.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/sessions" \  -H "Content-Type: application/json" \  -d '{    "project_id": "proj_01hexample"  }'
{  "session": {    "session_id": "sess_01J0Z9KX7Y0Q2Y7JX5M9K2YF3C",    "project_id": "proj_01hexample",    "state": "active",    "user_id": "user_id_12345",    "name": "Ada Lovelace",    "email": "ada@example.com",    "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"  },  "session_token": "stok_abc123def456"}
{  "code": "string",  "message": "string",  "details": {}}

{  "code": "auth.unauthorized",  "message": "The request lacks valid authentication credentials."}