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).
oauth2 auth_attempt.readAuthorizationBearer <token>Scope: auth_attempt.read
attempt_id*stringThe unique identifier of the authentication attempt
^att_[a-zA-Z0-9_-]+$Current state of the authentication attempt
application/json- response
The current state of an authentication attempt.
An attempt is an ephemeral state machine (15-minute TTL) that drives a single authentication round. It accepts factor challenges, verifies proofs, and completes into a handoff token. Clients drive the attempt by:
- Issuing challenges: POST /auth_attempts/{attempt_id}/challenges
- Verifying proofs: POST /auth_attempts/{attempt_id}/challenges/{challenge_id}/verify
- Completing: POST /auth_attempts/{attempt_id}/handoff
attempt_id*attempt-idUnique identifier for this authentication attempt (dialect-minted prefixed opaque string).
^att_[a-zA-Z0-9_-]+$project_id*project-id^[a-zA-Z0-9_-]+$state*stringOverall state of the authentication attempt:
in_progress: factors are still being collected; continue issuing challenges.completed: all required factors have been verified; the attempt is ready for handoff.failed: the attempt has failed (e.g. too many failed proofs) and cannot be continued.expired: the 15-minute TTL has been exceeded.
"in_progress""completed""failed""expired"session_id?|The session being authenticated into. Either newly created or passed in on POST. For step-up (re-auth), this is the existing session_id provided on creation.
user_id?|The user ID, if known at this point in the flow. Null until an identifier challenge has been verified.
required_factors?array<>The authentication factor methods that the project policy requires in order to complete this attempt. Computed by the server from the project's auth policy. Clients should use this to determine which challenges still need to be issued.
completed_factors?array<>The factors that have been successfully verified in this attempt so far. Each item includes method-specific metadata in the payload field.
The flow engine uses verified_at timestamps to enforce time-based policies, such as requiring password verification within the last 5 minutes for step-up auth to access sensitive operations.
A factor appears here once its challenge reaches verified state.
challenges?array<>All challenges issued within this attempt, in creation order. Use this to track the state of each factor challenge (pending, verified, failed, expired).
expires_at?stringWhen this attempt expires (15-minute TTL from creation)
date-timecreated_at*stringWhen this attempt was created
date-timecurl -X GET 'https://example.com/auth_attempts/string'{ "attempt_id": "string", "project_id": "string", "state": "in_progress", "session_id": "string", "user_id": "string", "required_factors": [ "identifier" ], "completed_factors": [ { "method": "identifier", "verified_at": "2019-08-24T14:15:22Z", "payload": { "method": "identifier", "user_id": "string" } } ], "challenges": [ { "challenge_id": "string", "method": "identifier", "state": "pending", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "payload": {} } ], "expires_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z"}