Verify a factor proof
Submits a proof (credential, code, assertion) to verify a factor challenge. The proof format depends on the challenge method. For example: - `password` method: { password: "…" } - `totp` method: { totp: { code: "123456" } } - `passkey` method: { passkey: { assertion: "…" } } - `recovery_code` method: { recovery_code: "…" } On successful verification, the factor is written to the auth attempt. The attempt moves to the next pending challenge or completes if all required factors are verified.
Submits a proof (credential, code, assertion) to verify a factor challenge.
The proof format depends on the challenge method. For example:
passwordmethod: { password: "…" }totpmethod: { totp: { code: "123456" } }passkeymethod: { passkey: { assertion: "…" } }recovery_codemethod: { recovery_code: "…" }
On successful verification, the factor is written to the auth attempt. The attempt moves to the next pending challenge or completes if all required factors are verified.
Authorization
oauth2 auth_attempts.writeIn: header
Scope: auth_attempts.write
Path Parameters
The unique identifier of the authentication attempt
The unique identifier of this challenge.
Header Parameters
Optional retry key for safe retries of the verification request. If a request with the same key has already been processed, the original response is returned. This prevents duplicate processing of the same proof in case of network issues or client retries.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Proof for verifying a factor challenge.
The exact format depends on the challenge method. The proof object should contain only the credential/code/assertion relevant to the challenge method being verified.
Proof for identifier method
Response Body
application/json
application/json
curl -X POST "https://example.com/auth_attempts/abc123def456/challenges/abc123def456/verify" \ -H "Content-Type: application/json" \ -d '{ "login_name": "alice@acme.com" }'{ "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."}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.
Complete authentication and create handoff token POST
Completes the authentication attempt and mints a `handoff_token`. Call this after all required factors have been verified and the attempt is in `completed` state. The handoff token is short-lived (≤60 seconds) and must be exchanged at POST /sessions/exchange to receive the final session and session_token. The handoff token is: - Single-use (atomic exchange, no retry) - Audience-bound (requires matching project key for exchange) - Idempotency-safe within a 5-minute window (see conventions)