Verify OTP

Verify email address using the 6-digit OTP code received via email.

Quick Navigation

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

Endpoint

POST /api/v1/auth/verify-otp

Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
  "temporary_token": "temp_token_from_signup",
  "otp_code": "123456"
}

Parameters

Field	Type	Required	Description
temporary_token	string	Yes	Temporary token from signup or resend OTP
otp_code	string	Yes	6-digit OTP code from email

Validations

• Temporary token validation
• OTP code format (6 digits)
• OTP expiration check (10 minutes)
• Attempt limit (5 max attempts)
• OTP code verification

Response

Success (200)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer",
    "expires_in": 3600,
    "user_id": 123,
    "email": "user@example.com",
    "is_verified": true,
    "message": "OTP verified successfully"
  },
  "message": "OTP verified successfully"
}

Error Codes

Status	Code	Description
400	INVALID_OTP	Invalid OTP code
410	OTP_EXPIRED	OTP code expired
422	VALIDATION_ERROR	Request validation failed
429	TOO_MANY_ATTEMPTS	Maximum attempts exceeded (5 attempts)

Data Flow

1. Token Validation

   • Validate temporary token from Redis
   • Check token expiration
   • Extract user and session information

2. OTP Verification

   • Retrieve OTP from Redis
   • Check OTP expiration (10 minutes)
   • Verify OTP code matches
   • Check attempt counter

3. Attempt Limit Check

   • Track failed attempts
   • Block after 5 failed attempts
   • Reset on successful verification

4. Email Verification

   • Mark email as verified
   • Update UserEmail.verified = true

5. Token Generation

   • Generate OAuth2 access token
   • Generate refresh token
   • Create session

6. Token Cleanup

   • Invalidate temporary token
   • Remove OTP from Redis

7. Audit Logging

   • Log successful verification
   • Record IP and user agent

Features

• OTP validation and expiration check
• Attempt limit (5 attempts max)
• Idempotent operation (already verified returns success)
• Audit logging
• Email verification status update
• Returns OAuth2 tokens (access + refresh)
• Session creation

Example

curl -X POST https://api.rivergen.com/api/v1/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "temporary_token": "temp_token_abc123",
    "otp_code": "123456"
  }'

Related Endpoints

• Signup - User registration
• Resend Signup OTP - Resend OTP
• Verify Email - Verify with token