Create TOTP Device

Register a new TOTP device for a user

Endpoint

POST /recipe/totp/device

This is an app-specific API that creates a new TOTP device for a user. The response includes a secret key that should be used to generate a QR code for the user to scan with their authenticator app.

Request Body

userId · string · required

The ID of the user creating the TOTP device. Cannot be empty.

deviceName · string

A friendly name for the device (e.g., “Google Authenticator”, “iPhone”). If not provided, a name will be auto-generated. Cannot be empty string if provided.

skew · number · required

The number of time windows to check before and after the current time. Must be >= 0. Recommended value: 1.

period · number · required

The time period in seconds for TOTP code generation. Must be > 0. Standard value: 30.

Request Example

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

Response

Success Response

status · string

Returns "OK" when the device is successfully created

deviceName · string

The name assigned to the device (auto-generated if not provided in request)

secret · string

The secret key for the TOTP device. This should be used to generate a QR code for the user to scan. This is only returned once - store it securely if needed.

{
  "status": "OK",
  "deviceName": "Google Authenticator",
  "secret": "JBSWY3DPEHPK3PXP"
}

Error Response

status · string

Returns "DEVICE_ALREADY_EXISTS_ERROR" when a device with the specified name already exists for this user

{
  "status": "DEVICE_ALREADY_EXISTS_ERROR"
}

Implementation Details

Source: View source

• This API requires public tenant access
• The device is created in an unverified state
• The user must verify the device using the Verify Device endpoint before it can be used for authentication
• The secret key is base32-encoded and compatible with standard authenticator apps
• Each user can have multiple TOTP devices with different names
• The hashing algorithm and TOTP length (6-8 digits) are not configurable at creation time

Next Steps

After creating a device:

1. Generate a QR code from the secret key
2. Display the QR code to the user to scan with their authenticator app
3. Ask the user to enter a TOTP code to verify the device
4. Call the Verify Device endpoint with the user’s code

Verify TOTP Device

Learn how to verify the newly created device

Error Responses

error · BadRequestException

Returned when:

• userId is empty
• deviceName is an empty string (null is allowed)
• skew is less than 0
• period is less than or equal to 0