Setup TOTP

Individual API

Initialize TOTP (Time-based One-Time Password) MFA setup using authenticator apps.

Quick Navigation

• Endpoint
• Headers
• Request Body
• Parameters
• Response
• Error Codes
• Features
• Next Steps
• Example
• Related Endpoints

Endpoint

POST /api/v1/mfa/totp/setup

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>
Content-Type	Yes	application/json

Request Body

{
  "device_name": "iPhone Authenticator"
}

Parameters

Field	Type	Required	Description
device_name	string	Yes	Name for the TOTP device

Response

Success (200)

{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code": "data:image/png;base64,iVBORw0KG...",
    "manual_entry_key": "JBSWY3DPEHPK3PXP",
    "device_name": "iPhone Authenticator",
    "backup_codes": [
      "ABCD1234",
      "EFGH5678",
      ...
    ]
  },
  "message": "TOTP setup initiated successfully"
}

Error Codes

Status	Code	Description
400	VALIDATION_ERROR	Invalid request
401	UNAUTHORIZED	Invalid or missing token
409	TOTP_ALREADY_ENABLED	TOTP already enabled for user

Features

• Generates TOTP secret and QR code
• Provides manual entry key
• Generates backup codes (10 codes)
• Rate limiting protection
• MFA remains inactive until verified

Next Steps

After receiving the QR code or secret:

1. Scan QR code with authenticator app (Google Authenticator, Authy, etc.)
2. Use Verify TOTP Setup to verify and activate

Example

curl -X POST https://api.rivergen.com/api/v1/mfa/totp/setup \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "iPhone Authenticator"
  }'

Related Endpoints

• Verify TOTP Setup - Verify and activate TOTP
• List TOTP Devices - View registered devices
• Generate Backup Codes - Regenerate backup codes