Issue a factor challenge
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.
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.
Authorization
oauth2 auth_attempts.writeIn: header
Scope: auth_attempts.write
Path Parameters
The unique identifier of the authentication attempt
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request to issue a factor challenge.
The method field selects which factor to challenge. Additional fields are
only relevant for specific methods:
passkey_optionsis optional and only used whenmethodispasskey.idp_provideris required whenmethodisidpand must be omitted otherwise. This conditional requirement is enforced server-side.
Response Body
application/json
application/json
curl -X POST "https://example.com/auth_attempts/abc123def456/challenges" \ -H "Content-Type: application/json" \ -d '{ "method": "password" }'{ "challenge_id": "abc123def456", "method": "password", "state": "pending", "created_at": "2026-04-28T15:31:00Z", "expires_at": "2026-04-28T15:41:00Z", "payload": {}}{ "code": "att.not_found", "message": "The auth attempt was not found."}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).
Verify a factor proof POST
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.