Request Email Update

Request to update user's email address. Stores new email temporarily and sends OTP.

Quick Navigation

• Endpoint
• Headers
• Request Body
• Parameters
• Validations
• Response
• Success (200)
• Error Codes
• Data Flow
• Features
• Next Steps
• Example
• Related Endpoints

Endpoint

POST /api/v1/auth/me/email/request

Headers

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

Request Body

{
  "new_email": "newemail@example.com"
}

Parameters

Field	Type	Required	Description
new_email	string	Yes	New email address to set

Validations

• Email format validation (RFC 5322)
• Email uniqueness check (must not be taken)
• New email must differ from current email
• Authentication required

Response

Success (200)

{
  "success": true,
  "data": {
    "message": "OTP sent to new email address",
    "new_email": "newemail@example.com"
  },
  "message": "OTP sent to new email address"
}

Error Codes

Status	Code	Description
400	EMAIL_UPDATE_REQUEST_FAILED	Request failed
400	EMAIL_ALREADY_TAKEN	Email already registered
401	UNAUTHORIZED	Invalid or missing token
422	VALIDATION_ERROR	Request validation failed

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. Email Validation

   • Validate email format
   • Check if email is already taken
   • Verify new email differs from current

3. Request Storage

   • Store email update request in Redis (10 minutes)
   • Key: email_update:{user_id}

4. OTP Generation

   • Generate 6-digit OTP code
   • Store OTP in Redis (10 minutes)

5. Email Sending

   • Send OTP to new email address
   • Queue email via email service

6. Audit Logging

   • Log email update request
   • Record new email (hashed)

Features

• Validates new email is not already taken
• Stores request temporarily in Redis (10 minutes)
• Sends OTP to new email address
• Only updates email after OTP verification
• Prevents email enumeration

Next Steps

After receiving OTP:

1. Use Verify Email Update endpoint
2. Provide OTP code
3. Email is updated after verification

Example

curl -X POST https://api.rivergen.com/api/v1/auth/me/email/request \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "new_email": "newemail@example.com"
  }'

Related Endpoints

• Verify Email Update - Verify OTP and update email
• Get Current User - View current email