Create Session

Create a new session with initial verification checks

Creates a new session with initial checks, metadata, and challenges for further verification. Returns a session token that can be used for authentication.

HTTP Request

POST /v2/sessions

Request Body

checks · object

The checks to be performed during session creation. On successful checks, the session’s factors will be updated.

user · object

Check the user by ID or login name. A user check can only be performed once per session.

user_id · string

The unique identifier of the user to check (1-200 characters).

login_name · string

The login name of the user to check (1-200 characters). Search is case insensitive.

password · object

Check the password. Requires that the user is already checked.

password · string · required

The password to verify (1-200 characters).

web_auth_n · object

Check WebAuthN credential. Requires user check and a previously requested challenge.

credential_assertion_data · object · required

JSON representation of the public key credential from the WebAuthN client.

totp · object

Check TOTP code. Requires that the user is already checked.

code · string · required

The 6-digit TOTP code.

otp_sms · object

Check OTP sent via SMS. Requires that the user is already checked.

code · string · required

The OTP code received via SMS.

otp_email · object

Check OTP sent via email. Requires that the user is already checked.

code · string · required

The OTP code received via email.

metadata · object

Custom key-value pairs to store on the session. Values are stored as bytes.

challenges · object

Challenges to request for further verification. The challenges will be returned in the response.

user_agent · object

Information about the client creating the session.

fingerprint_id · string

Unique identifier for the user agent’s fingerprint.

ip · string

IP address from which the session is created.

description · string

Human-readable description of the user agent.

header · object

HTTP headers from the client request.

lifetime · string

Duration after which the session will be automatically invalidated (e.g., “18000s” for 5 hours). If not set, the session will not expire automatically.

Response

details · object

Metadata about the operation.

sequence · string

The sequence number of this change.

change_date · timestamp

When the session was created.

resource_owner · string

The resource owner of the session.

session_id · string

Unique identifier of the newly created session.

session_token · string

The session token to use for authentication. This can be used as an OAuth2 access token or to authenticate OIDC/SAML requests.

challenges · object

The challenges that were requested for the session, ready for use in subsequent checks.

Example Request

curl -X POST 'https://api.zitadel.cloud/v2/sessions' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "checks": {
      "user": {
        "login_name": "[e-mail]"
      },
      "password": {
        "password": "MySecurePassword123!"
      }
    },
    "user_agent": {
      "ip": "192.168.1.100",
      "description": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
    },
    "lifetime": "28800s"
  }'

Example Response

{
  "details": {
    "sequence": "2",
    "change_date": "2024-03-15T10:30:00.000Z",
    "resource_owner": "69629023906488334"
  },
  "session_id": "222430354126975533",
  "session_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIy...",
  "challenges": {}
}

Error Responses

Status Code	Description
400	Invalid request body or failed verification
401	Unauthorized - missing or invalid authentication
403	Forbidden - insufficient permissions

Notes

• A user check can only be performed once per session and cannot be changed afterwards
• Some checks require the user to be verified first (password, TOTP, OTP)
• Other checks require a previously requested challenge (WebAuthN, IDP intent)
• The session token should be kept secure and treated like an access token
• Previous session tokens are invalidated when the session is updated