Forgot Password

Request a password reset code via email

POST /api/v1/auth/forgot-password

Forgot Password

cURL

curl --request POST \
  --url https://api.example.com/api/v1/auth/forgot-password \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>"
}
'

200

{
  "success": true,
  "data": {
    "email": "<string>"
  },
  "message": "<string>"
}

Endpoint

POST /api/v1/auth/forgot-password

Base URL: http://localhost:3000/api/v1

This endpoint is public and does not require authentication.

Request Body

email · string · required

The email address associated with the account. Works for both job seekers and companies.

Request Shape

interface ForgotPasswordDto {
  email: string;
}

Response

Success Response (200 OK)

interface ForgotPasswordResponse {
  success: boolean;
  data: {
    email: string;
  };
  message: string;
  meta: {
    timestamp: string;
    path: string;
    method: string;
  };
}

{
  "success": true,
  "data": {
    "email": "[e-mail]"
  },
  "message": "If an account exists with that email, you'll receive a password reset link shortly.",
  "meta": {
    "timestamp": "2026-04-23T20:00:00.000Z",
    "path": "/auth/forgot-password",
    "method": "POST"
  }
}

success · boolean

Always true for successful requests.

data · object

Contains the submitted email address.

Show Properties

email · string

The email address that was submitted.

message · string

Generic success message that doesn’t reveal if the email exists in the system.

Security Behavior

Email Enumeration Prevention: This endpoint always returns the same success response, regardless of whether the email exists in the database. This prevents attackers from discovering valid email addresses.

What Actually Happens

1. Immediate Response

   API returns success response immediately without waiting for email lookup.

2. Background Processing

   System searches for the account in both JobSeeker and Company tables (asynchronously).

3. Email Exists

   If account is found: - Generate 6-digit OTP code - Store OTP in Redis with 10-minute expiration - Queue password reset email for delivery - Email is sent with the reset code

4. Email Doesn't Exist

   If account is not found: - Process silently terminates - No email is sent - User sees same response as successful case

Email Content

If the email exists, the user receives an email containing:

• 6-digit OTP code
• Instructions to use the reset password endpoint
• Expiration notice (10 minutes)
• Security warnings
• Information about account protection

OTP Details

OTP Validity: Each password reset code is valid for 10 minutes from generation. After expiration, users need to request a new code.

OTP Format: The code is a 6-digit numeric string (e.g., 123456). Only numbers are allowed.

Maximum Attempts: Each OTP can be attempted a maximum of 3 times. After 3 failed attempts, the code is invalidated and a new request is required.

Error Responses

400 Bad Request - Validation Error

Returned when request validation fails.

{
  "success": false,
  "error": {
    "message": ["email must be an email"],
    "statusCode": 400,
    "timestamp": "2026-04-23T20:00:00.000Z",
    "path": "/auth/forgot-password",
    "method": "POST",
    "details": "Bad Request"
  }
}

Common validation errors:

• email must be an email - Invalid email format
• email should not be empty - Email field is missing

Validation Rules

Field	Type	Required	Rules
email	string	Yes	Must be valid email format

Rate Limiting Considerations

Best Practice: Implement rate limiting on the client side to prevent abuse. Consider limiting requests to 3 attempts per email per hour.

While the API doesn’t currently enforce rate limiting, excessive requests may be throttled in the future.

Response Time

The response is designed to be consistent regardless of whether the email exists:

• ✅ Same response time (~50-100ms)
• ✅ Same HTTP status code (200)
• ✅ Same response structure
• ✅ No indication of email existence

This prevents timing attacks that could reveal valid email addresses.

Next Steps

After receiving the password reset code via email:

1. Use the code with the Reset Password endpoint
2. Enter the 6-digit code along with the email and new password
3. Wait for confirmation that password has been reset
4. Login with the new password using the Login endpoint

Important Notes

Automatic User Type Detection: The system automatically determines whether the account is a Job Seeker or Company account. You don’t need to specify the user type.

Multiple Requests: If a user requests a password reset multiple times, each new OTP overwrites the previous one. Only the most recent OTP is valid.

Email Delivery: Email delivery may take a few seconds to a few minutes depending on email provider. If the user doesn’t receive the email: - Check spam/junk folder - Verify email address is correct - Request a new code after waiting a few minutes

Security Notes

Privacy First: This endpoint is designed with security and privacy in mind. It never reveals whether an email address is registered in the system.

Best Practices

1. Don’t reveal email existence - Use generic success messages
2. Consistent response times - Prevent timing attacks
3. Time-limited OTPs - Codes expire after 10 minutes
4. Attempt limiting - Maximum 3 verification attempts per OTP
5. Single-use codes - Each OTP can only be used once successfully

Related Endpoints

• Reset Password - Complete password reset with OTP code
• Login - Login after resetting password
• Register Job Seeker - Create new job seeker account
• Register Company - Create new company account