Verify Email

Verify email address using the verification token 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-email

Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
  "token": "verification_token_from_email"
}

Parameters

Field	Type	Required	Description
token	string	Yes	Email verification token from email link

Validations

• Token format validation
• Token expiration check (10 minutes for signup, configurable)
• Token signature verification
• User account status check

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": "Email verified successfully"
  },
  "message": "Email verified successfully"
}

Error Codes

Status	Code	Description
400	INVALID_TOKEN	Invalid verification token
410	TOKEN_EXPIRED	Verification token expired
422	VALIDATION_ERROR	Request validation failed

Data Flow

1. Token Validation

   • Validate token format and signature
   • Check token expiration
   • Extract user information from token

2. Email Verification

   • Mark email as verified in database
   • Update UserEmail.verified = true
   • Set email as primary if first email

3. Idempotent Check

   • If already verified, still return success
   • Return existing tokens if available

4. Token Generation

   • Generate OAuth2 access token (1 hour expiry)
   • Generate refresh token (30 days expiry)
   • Create session record

5. Session Creation

   • Create session with IP and user agent
   • Set session expiration based on remember_me

6. Audit Logging

   • Log email verification event
   • Record verification timestamp

7. Token Invalidation

   • Invalidate temporary token from Redis
   • Clean up verification records

Features

• Token validation and expiration check
• Idempotent operation (already verified returns success)
• Audit logging
• Email verification status update
• Returns OAuth2 tokens (access + refresh)
• Session creation upon verification

Example

curl -X POST https://api.rivergen.com/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "verification_token_xyz789"
  }'

Related Endpoints

• Signup - User registration
• Resend Signup OTP - Resend verification code
• Verify OTP - Verify with OTP code