Get authentication attempt state
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).
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).
Authorization
oauth2 auth_attempts.readIn: header
Scope: auth_attempts.read
Path Parameters
The unique identifier of the authentication attempt
Response Body
application/json
application/json
curl -X GET "https://example.com/auth_attempts/abc123def456"{ "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.not_found", "message": "The auth attempt was not found."}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.
Issue a factor challenge POST
Issues a single-factor verification challenge within an auth attempt. This advances the authentication state machine by requesting a specific factor method (password, passkey, TOTP, OTP via SMS, etc.). The server responds with challenge details including method, metadata, and any UI hints. The client then verifies the proof by calling POST /auth_attempts/{attempt_id}/challenges/{challenge_id}/verify.