Forgot Password

Request a password reset email. If the email address exists in the system, a secure reset link will be sent.

Request

Body Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Email address associated with the account

Example Request

curl -X POST https://api.storno.ro/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

const response = await fetch('https://api.storno.ro/api/auth/forgot-password', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
  }),
});

if (response.ok) {
  console.log('Password reset email sent (if account exists)');
}

$client = new \GuzzleHttp\Client();

$response = $client->post('https://api.storno.ro/api/auth/forgot-password', [
    'json' => [
        'email' => '[email protected]',
    ],
]);

// Always returns 200, even if email doesn't exist

Response

Success Response (200 OK)

The endpoint always returns a success response, regardless of whether the email exists. This prevents user enumeration attacks.

{
  "message": "If an account with that email exists, a password reset link has been sent."
}

Security Behavior

For security reasons, this endpoint:

Always returns 200 OK - Never reveals whether an email exists in the system
Sends email only if account exists - No email is sent for non-existent accounts
Rate limits aggressively - Prevents abuse and email bombing

Password Reset Email

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

A secure reset link valid for 1 hour
Instructions on how to reset their password
A warning that they didn't request this (if it wasn't them)
Link to contact support if needed

Example Email:

Subject: Reset Your Storno.ro Password

Hi John,

You recently requested to reset your password for your Storno.ro account.
Click the link below to reset it:

https://storno.ro/reset-password?token=abc123xyz...

This link will expire in 1 hour.

If you didn't request a password reset, you can safely ignore this email.
Your password will not be changed.

Need help? Contact us at [email protected]

Thanks,
The Storno.ro Team

Error Codes

Code	Description
`400`	Bad Request - Missing or invalid email address
`429`	Too Many Requests - Rate limit exceeded

Error Response Examples

Invalid Email Format (400)

{
  "code": 400,
  "message": "Validation failed",
  "errors": {
    "email": ["This value is not a valid email address."]
  }
}

Rate Limit Exceeded (429)

{
  "code": 429,
  "message": "Too many password reset requests. Please try again in 15 minutes."
}

Rate Limiting

To prevent abuse, password reset requests are rate-limited:

Per Email: Maximum 3 requests per hour per email address
Per IP: Maximum 10 requests per hour per IP address
Cooldown: 15 minutes between requests for the same email

Usage Notes

User Flow

User clicks "Forgot Password" on login page
User enters their email address
User submits the form
System shows generic success message
User checks email for reset link
User clicks link and is redirected to password reset page
User enters new password and confirms
User is redirected to login page with success message

Implementation Example

// Forgot password form handler
async function handleForgotPassword(email) {
  try {
    const response = await fetch('/api/auth/forgot-password', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    });

    if (response.ok) {
      showMessage(
        'If an account with that email exists, we\'ve sent password reset instructions.',
        'success'
      );
    }
  } catch (error) {
    showMessage('An error occurred. Please try again later.', 'error');
  }
}

Best Practices

Generic messaging - Never reveal if an email exists or not
Clear instructions - Tell users to check their email (including spam folder)
Expiry notice - Inform users the link expires in 1 hour
Alternative options - Provide support contact for users who can't access email
Resend option - Allow users to request another reset email after cooldown

Security Considerations

Reset tokens are single-use and expire after 1 hour
Tokens are cryptographically secure random strings
Using a reset token invalidates any previous tokens
Successfully resetting password invalidates all existing sessions
All password reset attempts are logged for security auditing

Reset Password - Complete the password reset with token
Login - Authenticate after resetting password
Register - Create a new account if you don't have one

Troubleshooting

User didn't receive email:

Check spam/junk folder
Verify email address is correct
Wait a few minutes (email delivery can be delayed)
Try requesting another reset after cooldown period
Contact support if issue persists

Reset link expired:

Request a new password reset
Complete the process within 1 hour

Multiple reset requests:

Only the most recent token is valid
Previous tokens are automatically invalidated