Verify TOTP Setup

Verify TOTP code and enable MFA for the user.

Endpoint

POST /api/v1/mfa/totp/verify

Headers

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

Request Body

{
  "code": "123456",
  "device_name": "iPhone 14"
}

Parameters

Field	Type	Required	Description
code	string	Yes	6-digit TOTP code from authenticator app
device_name	string	No	Optional device name for the credential

Validations

• TOTP code format (6 digits)
• Code verification against pending setup
• Rate limiting (3 attempts, 60s lockout)
• Device name validation (if provided)

Response

Success (200)

{
  "success": true,
  "data": {
    "success": true,
    "backup_codes": [
      "ABCD-1234",
      "EFGH-5678",
      "..."
    ],
    "message": "TOTP MFA enabled successfully"
  },
  "message": "TOTP MFA enabled successfully"
}

Error Codes

Status	Code	Description
400	INVALID_CODE	Invalid TOTP code
400	NO_PENDING_SETUP	No pending TOTP setup found
401	UNAUTHORIZED	Invalid or missing token
422	VALIDATION_ERROR	Request validation failed
429	TOO_MANY_ATTEMPTS	Too many failed attempts (3 max)

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. Pending Setup Check

   • Retrieve pending TOTP setup from database
   • Verify setup exists and is not expired

3. Code Verification

   • Verify TOTP code using stored secret
   • Check time window tolerance
   • Track verification attempts

4. Rate Limiting

   • Check attempt counter
   • Lock if 3 failed attempts (60 seconds)
   • Reset counter on success

5. MFA Activation

   • Mark TOTP method as verified
   • Enable MFA for user
   • Set device name if provided

6. Backup Code Generation

   • Generate 10 backup codes
   • Store hashed codes in database
   • Return plain codes to user

7. Audit Logging

   • Log TOTP setup completion
   • Record device name

Features

• Validates 6-digit TOTP code
• Matches by device name if provided
• Enables MFA on successful verification
• Generates backup codes
• Rate limiting (3 attempts, 60s lockout)

Important Notes

• Backup codes are shown only once during setup
• User must save backup codes securely
• Each backup code can only be used once

Example

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

Related Endpoints

• TOTP Setup - Initiate TOTP setup
• MFA Status - Check MFA status