Skip to main content

​
Endpoint

POST /recipe/totp/verify
This is a tenant-specific API that verifies a TOTP code for authentication. This endpoint is used after a device has been verified, typically during login to implement multi-factor authentication.

​
Request Body

​
userId
string
required
The ID of the user attempting to authenticate. Cannot be empty.
​
totp
string
required
The TOTP code provided by the user from their authenticator app.

​
Request Example

curl -X POST https://your-api-domain.com/recipe/totp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "totp": "123456"
  }'

​
Response

​
Success Response

​
status
string
Returns "OK" when the TOTP code is valid
{
  "status": "OK"
}

​
Error Responses

​
Unknown User ID

​
status
string
Returns "UNKNOWN_USER_ID_ERROR" when the user has no verified TOTP devices
{
  "status": "UNKNOWN_USER_ID_ERROR"
}

​
Invalid TOTP Code

​
status
string
Returns "INVALID_TOTP_ERROR" when the provided code is incorrect
​
currentNumberOfFailedAttempts
number
The number of failed attempts so far (available in v5.0+)
​
maxNumberOfFailedAttempts
number
The maximum number of failed attempts allowed (available in v5.0+)
{
  "status": "INVALID_TOTP_ERROR",
  "currentNumberOfFailedAttempts": 3,
  "maxNumberOfFailedAttempts": 5
}

​
Rate Limit Reached

​
status
string
Returns "LIMIT_REACHED_ERROR" when too many failed attempts have occurred
​
retryAfterMs
number
The number of milliseconds to wait before retrying
​
currentNumberOfFailedAttempts
number
The number of failed attempts (available in v5.0+)
​
maxNumberOfFailedAttempts
number
The maximum allowed failed attempts (available in v5.0+)
{
  "status": "LIMIT_REACHED_ERROR",
  "retryAfterMs": 300000,
  "currentNumberOfFailedAttempts": 5,
  "maxNumberOfFailedAttempts": 5
}

​
Implementation Details

Source: View source
  • This endpoint checks the TOTP code against all verified devices for the user
  • If the code matches any verified device, authentication succeeds
  • Failed attempts are tracked per user to prevent brute force attacks
  • Rate limiting is enforced after reaching the maximum number of failed attempts
  • The code is checked using the device’s configured skew and period parameters

​
Typical MFA Flow

  1. User completes primary authentication (e.g., email/password)
  2. Application prompts for TOTP code
  3. User opens authenticator app and enters the current code
  4. Application calls this endpoint to verify the code
  5. If successful (status: "OK"), user is fully authenticated
  6. If failed, show error and allow retry (respecting rate limits)

​
Security Considerations

  • Always implement rate limiting on the client side based on the response
  • Display retryAfterMs to users when rate limited
  • Track failed attempts and warn users before reaching the limit
  • Consider implementing account lockout after multiple failed MFA attempts

​
Error Handling

​
error
BadRequestException
Returned when userId is empty

Create TOTP Device

Register a new authenticator device

Verify Device

Verify a newly created device

Build docs developers (and LLMs) love

Get started for freeTalk to us