Skip to main content

​
Endpoint

POST /recipe/totp/device/verify
This is a tenant-specific API that verifies a newly created TOTP device by checking if the provided code is valid. Once verified, the device can be used for authentication.

​
Request Body

​
userId
string
required
The ID of the user who owns the device. Cannot be empty.
​
deviceName
string
required
The name of the device to verify. Cannot be empty.
​
totp
string
required
The TOTP code generated by the authenticator app.

​
Request Example

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

​
Response

​
Success Response

​
status
string
Returns "OK" when the device is successfully verified
​
wasAlreadyVerified
boolean
  • true if the device was already verified before this call
  • false if this call newly verified the device
{
  "status": "OK",
  "wasAlreadyVerified": false
}

​
Error Responses

​
Unknown Device

​
status
string
Returns "UNKNOWN_DEVICE_ERROR" when the specified device does not exist
{
  "status": "UNKNOWN_DEVICE_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": 2,
  "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
  • Verification is tenant-specific
  • Failed attempts are tracked to prevent brute force attacks
  • After reaching the maximum failed attempts, users must wait before retrying
  • Once verified, a device can be used for authentication
  • Verifying an already-verified device is not an error - returns success with wasAlreadyVerified: true

​
Workflow

  1. User creates a TOTP device using Create Device
  2. User scans QR code with authenticator app
  3. User enters the 6-digit code from their app
  4. Your application calls this endpoint to verify the code
  5. If successful, the device is now verified and can be used for authentication

​
Next Steps

Verify TOTP Code

Use the verified device for authentication

​
Error Handling

​
error
BadRequestException
Returned when:
  • userId is empty
  • deviceName is empty

Build docs developers (and LLMs) love

Get started for freeTalk to us