Post
/api/v1/twoFactorChallenges.verifyChallenge
Verifies a two-factor authentication code submitted against a pending challenge and, on success, returns a login token for the associated user. Use this endpoint to complete the second factor of a login flow that issued a challengeId.
The endpoint does not require an authenticated session. It is rate-limited to 5 requests per minute per caller. Exceeding the per-user maximum failed attempts removes the challenge and returns a totp-max-attempts error.
Changelog
| Version | Description |
|---|---|
| 8.5.0 | Added |
Body parameters
Example 1
{
"challengeId": "8f4c2d1e9a7b6c5d3e2f1a0b",
"code": "482913"
}object
challengeId
string Required
The ID of the pending two-factor challenge returned by the login flow.
Example8f4c2d1e9a7b6c5d3e2f1a0b
code
string Required
The two-factor code provided by the user for the challenge.
Example482913
Responses
200
OK
Verification successful
{
"loginToken": "exampleLoginTokenString123",
"userId": "aobEdbYhXfu5hkeqG",
"success": true
}object
loginToken
string
userId
string
success
boolean
400
Bad Request
Missing parameters
{
"success": false,
"error": "challengeId and code are required",
"errorType": "error-parameter-required"
}Invalid code
{
"success": false,
"error": "Invalid code",
"errorType": "error-invalid-code"
}Challenge not found
{
"success": false,
"error": "challenge not found",
"errorType": "error-challenge-not-found"
}User not found
{
"success": false,
"error": "user not found",
"errorType": "error-user-not-found"
}Max attempts reached
{
"success": false,
"error": "TOTP Maximun Failed Attempts Reached",
"errorType": "totp-max-attempts"
}object
success
boolean
error
string
errorType
string