API DocsAPI Docs / POST /api/v1/auth/reset-password/request

POST /api/v1/auth/reset-password/request

Initiates a password reset process by sending a 6-digit verification code via SMS to the user's phone number.

Permissions

This endpoint does not require authentication. Rate limited to 5 requests per minute per IP address.

Request Body Parameters

Request Example

POST /api/v1/auth/reset-password/request
Content-Type: application/json

{
  "phone": "+989123456789"
}

Response

200 OK

Returned for every well-formed phone number, registered or not, with the same body. A code is generated and sent only when the number belongs to an account; an unregistered number gets this response and no SMS.

Example

{
  "message": "If an account exists for this number, a reset code has been sent."
}

Error Responses

422 Validation Error Examples

{
  "message": "The phone field is required.",
  "errors": {
    "phone": ["The phone field is required."]
  }
}

500 SMS Send Failure

{
  "message": "Failed to send SMS. Please try again."
}

How it works

1. Validates the phone number's shape. It does not check that the number is registered
2. If no account has this number, returns the 200 above and stops: no code, no SMS
3. Otherwise generates a 6-digit verification code
4. Stores the hashed code in the database with a 15-minute expiration and a fresh 5-guess allowance
5. Sends the code via an SMS.ir verify-send template
6. Returns the same success message (code is never returned in the response for security)

Security Notes

• The verification code is sent only via SMS to the registered phone number
• Codes expire after 15 minutes and are deleted after 5 wrong guesses (see reset)
• This endpoint does not reveal whether a number has an account: registered and unregistered numbers get the same 200 and body. Clients must therefore move to the code screen either way; an unregistered number's code is simply never accepted. Accepted residual: the 500 SMS failure can only happen for a registered number, because only a registered number is ever sent a code. Hiding it would leave a real user waiting for an SMS that never comes
• Accepted residual: timing. Both branches pay the same bcrypt hash, but a registered number also waits for the SMS gateway, which is called inline. A caller timing many requests can still tell the two apart. Closing it means queueing the SMS send, which would also remove the 500 above; that is a separate change (SMS.ir is listed as inline debt in rules/queues-and-jobs.md)
• Rate limiting prevents abuse
• The SMS body is defined by a template in the SMS.ir panel, not by this API: only the code is sent to the gateway

Related Resources

• POST /api/v1/auth/reset-password/reset - Reset password using verification code
• POST /api/v1/auth/login - User login