Verify Email OTP Setup

Verify Email OTP code and enable MFA for the user.

Endpoint

POST /api/v1/mfa/email-otp/verify

Headers

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

Request Body

{
  "code": "123456"
}

Parameters

Field	Type	Required	Description
code	string	Yes	6-digit OTP code from email

Validations

• OTP code format (6 digits)
• OTP code verification
• OTP expiration check (10 minutes)
• Rate limiting (3 attempts, 60s lockout)

Response

Success (200)

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

Error Codes

Status	Code	Description
400	INVALID_CODE	Invalid OTP code
400	NO_PENDING_SETUP	No pending Email OTP setup
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 Email OTP setup
   • Verify setup exists

3. OTP Verification

   • Retrieve OTP from Redis
   • Verify OTP code matches
   • Check OTP expiration
   • Track verification attempts

4. Rate Limiting

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

5. MFA Activation

   • Mark Email OTP method as verified
   • Enable MFA for user

6. Backup Code Generation

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

7. OTP Cleanup

   • Remove OTP from Redis
   • Clear pending setup state

8. Audit Logging

   • Log Email OTP setup completion

Features

• Validates 6-digit OTP code from email
• Enables MFA on successful verification
• Generates backup codes
• Rate limiting (3 attempts, 60s lockout)
• OTP expiration handling

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/email-otp/verify \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Related Endpoints

• Email OTP Setup - Initiate Email OTP setup
• MFA Status - Check MFA status