Forgot Password

Initiate password reset process by sending reset email.

Quick Navigation

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

Endpoint

POST /api/v1/auth/forgot-password

Headers

Header	Required	Description
Content-Type	Yes	application/json

Request Body

{
  "email": "user@example.com"
}

Parameters

Field	Type	Required	Description
email	string	Yes	User's email address

Validations

• Email format validation
• Rate limiting: 3 requests per hour per IP
• Always returns success (security measure)

Response

Success (200)

Always returns success, even if email doesn't exist:

{
  "success": true,
  "data": {
    "message": "If the email exists, a password reset link has been sent."
  },
  "message": "If the email exists, a password reset link has been sent."
}

Error Codes

Status	Code	Description
422	VALIDATION_ERROR	Request validation failed
429	RATE_LIMITED	Too many requests (3 per hour)

Security Note

This endpoint always returns 200 regardless of whether the email exists. This prevents email enumeration attacks where attackers can discover which emails are registered.

Data Flow

1. Rate Limiting

   • Check rate limit (3 per hour per IP)
   • Return 429 if exceeded

2. User Lookup

   • Find user by email (if exists)
   • Continue even if user not found

3. Token Generation (if user exists)

   • Generate secure reset token
   • Store in Redis with 1-hour expiration
   • Store one-time use flag

4. Email Sending (if user exists)

   • Send password reset email
   • Include reset link with token
   • Queue email via email service

5. Audit Logging

   • Log password reset request
   • Record IP address

6. Response

   • Always return success
   • Generic message (security)

Features

• Always returns 200 regardless of email existence (security)
• Generates secure token with 1-hour expiration
• Sends password reset email if user exists
• Rate limiting protection (3 requests per hour)
• Audit logging
• One-time use token

Example

curl -X POST https://api.rivergen.com/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Related Endpoints

• Reset Password - Complete password reset
• Login - Login after reset