Authentication Attempts
OpenAPI operations for the authentication attempt state machine.
Authentication attempts hold the short-lived state for a login, registration, step-up, or recovery journey. Use these endpoints to start an attempt, issue factor challenges, verify proofs, and mint a handoff token for session exchange.
Submit step data and advance POST
Submits user input for the current step. The server validates, processes (e.g., verifies a credential), advances the state machine through any invisible steps, and returns the next visible step. The response sets an updated encrypted `HttpOnly` cookie (`_zflow`) with the new flow state. The server is stateless — all orchestration state is carried in this cookie between requests. **Important:** The `id` in the response may differ from the `id` used in the request. This happens when a flow pivots (pushes a new flow onto the stack) or when a stacked flow completes (auto-pops to the parent flow). Always use the `id` from the latest response for the next request. ## Flow completion When `step.type` is `complete`, the flow is terminal. The `step.behavior` field tells the frontend what to do: | `behavior` | Action | |------------- |------------------------------------------------------------| | `redirect` | Navigate to `redirect_uri` (OIDC/SAML auth request done). | | `show` | Render the step as a success screen (e.g., registration). | A `complete` step is only returned when the **entire flow stack** is done. If a stacked flow (e.g., recovery pivoted from login) finishes, the server auto-pops to the parent flow and returns the parent's next step — the frontend never sees a `complete` for intermediate flows.
Create a new authentication attempt POST
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.