Verify TOTP Device

Verify a newly created TOTP device with a valid code

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