Setup Email OTP

Initiate Email OTP MFA setup by sending OTP to user's primary email.

Endpoint

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

Headers

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

Request Body

Empty body (no parameters required)

Validations

• User authentication required
• Email OTP must not already be enabled
• Primary email must be verified

Response

Success (200)

{
  "success": true,
  "data": {
    "message": "Email OTP setup initiated. Check your email for verification code.",
    "otp_sent": true
  },
  "message": "Email OTP setup initiated successfully"
}

Error Codes

Status	Code	Description
400	SETUP_FAILED	Setup failed
401	UNAUTHORIZED	Invalid or missing token
409	EMAIL_OTP_ALREADY_ENABLED	Email OTP already enabled
422	VALIDATION_ERROR	Request validation failed

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. Email OTP Check

   • Check if Email OTP is already enabled
   • Return error if already enabled

3. Primary Email Verification

   • Get user's primary email
   • Verify email is verified
   • Return error if not verified

4. OTP Generation

   • Generate 6-digit OTP code
   • Store OTP in Redis (10 minutes expiry)
   • Store setup state in database

5. Email Sending

   • Send OTP to primary email
   • Queue email via email service

6. Response

   • Return confirmation message
   • Indicate OTP sent

Features

• Sends OTP to user's primary email
• Generates backup codes after verification
• Rate limiting protection
• Requires verified email address

Next Steps

After receiving OTP:

1. User enters OTP code from email
2. Use Verify Email OTP endpoint
3. Email OTP MFA is enabled after verification

Example

curl -X POST https://api.rivergen.com/api/v1/mfa/email-otp/setup \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json"

Related Endpoints

• Verify Email OTP - Verify OTP and enable MFA
• MFA Status - Check current MFA status