password reset email API

Here’s a simple password reset email API design you can use.

Typical flow

1. User submits their email address.
2. Your API generates a one-time reset token with an expiration time.
3. API sends an email containing a reset link.
4. User clicks the link and sets a new password.
5. API verifies token and updates the password.

---

Endpoint example

POST /auth/forgot-password

Request

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

Response

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

---

Secure behavior

• Always return the same response, even if the email does not exist.
• Use a random, high-entropy token.
• Store only a hashed version of the token in the database.
• Set an expiration time, e.g. 15–60 minutes.
• Invalidate the token after it is used.
• Rate limit requests to prevent abuse.

---

Email content example

Subject: Reset your password

Body:

We received a request to reset your password.

Click here to reset it:
https://yourapp.com/reset-password?token=RESET_TOKEN

This link expires in 30 minutes.

If you didn’t request this, you can ignore this email.

---

Backend logic example

Pseudo-flow:

def forgot_password(email):
    user = find_user_by_email(email)

    # Always respond success
    if not user:
        return

    token = generate_secure_token()
    token_hash = hash_token(token)
    save_reset_token(user.id, token_hash, expires_in=30_minutes)

    send_email(
        to=email,
        subject="Reset your password",
        body=f"https://yourapp.com/reset-password?token={token}"
    )

---

Password reset endpoint

POST /auth/reset-password

Request

{
  "token": "reset-token-here",
  "newPassword": "NewStrongPassword123!"
}

Behavior

• Validate token
• Check expiration
• Update password hash
• Delete/disable the token

Response

{
  "message": "Password reset successful."
}

---

Recommended extras

• Use HTTPS only
• Add CAPTCHA or rate limiting after repeated attempts
• Log reset requests for security monitoring
• Send a notification email after password change

If you want, I can also provide:

1. a Node.js/Express implementation
2. a Python/FastAPI implementation
3. a Laravel/Django example
4. a full OpenAPI spec