Zitadel Preview Docs
API referenceAuthentication Attempts

Create a new authentication attempt

Starts a new authentication attempt. This is the entry point for the auth_attempts state machine. An attempt is an ephemeral (15-minute TTL) state machine that drives a single authentication round. It accepts factor challenges, verifies proofs, and completes into a session or handoff token. Accepts a project_id and challenge_nonce (from POST /bootstrap/challenge). For step-up re-auth, also include session_id to add factors to an existing session.

POST
/auth_attempts

Starts a new authentication attempt. This is the entry point for the auth_attempts state machine.

An attempt is an ephemeral (15-minute TTL) state machine that drives a single authentication round. It accepts factor challenges, verifies proofs, and completes into a session or handoff token.

Accepts a project_id and challenge_nonce (from POST /bootstrap/challenge). For step-up re-auth, also include session_id to add factors to an existing session.

Authorization

oauth2 auth_attempts.write
AuthorizationBearer <token>

In: header

Scope: auth_attempts.write

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create a new authentication attempt

Response Body

application/json

application/json

curl -X POST "https://example.com/auth_attempts" \  -H "Content-Type: application/json" \  -d '{    "project_id": "river-8421"  }'
{  "attempt_id": "abc123def456",  "project_id": "river-8421",  "state": "in_progress",  "session_id": "abc123def456",  "user_id": "user_id_12345",  "required_factors": [    "identifier",    "password"  ],  "completed_factors": [    {      "method": "password",      "verified_at": "2026-04-28T15:32:00Z",      "payload": {        "user_id": "user_id_12345"      }    }  ],  "challenges": [    {      "challenge_id": "abc123def456",      "method": "password",      "state": "pending",      "created_at": "2026-04-28T15:31:00Z",      "expires_at": "2026-04-28T15:41:00Z",      "payload": {}    }  ],  "expires_at": "2026-04-28T15:45:00Z",  "created_at": "2026-04-28T15:30:00Z"}

{  "code": "att.invalid_request",  "message": "invalid request"}

Authentication Attempts

OpenAPI operations for the authentication attempt state machine.

Get authentication attempt state GET

Polls the current state of an authentication attempt. Returns the attempt's state, available factors for the next challenge, challenges issued so far, and any errors preventing progress. Use this for polling during long-running factor verifications (e.g., waiting for a federated IdP callback or a device flow).