Password reset emails: token design and delivery checklist

A password reset email is a key to the account, delivered by a channel you do not control, to a mailbox that may or may not still belong to your user. Most account takeovers that go through email exploit a weakness in how the reset token was designed or how the flow behaves, not in the email itself.

Token design#

Make tokens unguessable#

Generate reset tokens with a cryptographically secure random number generator and enough entropy that guessing is hopeless. 128 bits or more is a common choice.

import secrets, hashlib

token = secrets.token_urlsafe(32)            # ~256 bits, URL-safe
token_hash = hashlib.sha256(token.encode()).hexdigest()
# store token_hash with user_id, created_at, expires_at; email the raw token

Never derive tokens from predictable values such as user IDs, timestamps or email addresses, even with hashing.

Store only a hash#

Treat reset tokens like passwords in your database. Store a hash, not the raw token. If the database leaks, outstanding reset links remain unusable. Because the token already has high entropy, a fast hash such as SHA-256 is adequate here; a slow password hash is not required.

Expire quickly#

Reset links should expire within a short window. OWASP's guidance treats short lifetimes as essential, and many applications use somewhere between 15 minutes and an hour. Long-lived reset links sit in mailboxes, backups and forwarded threads.

Single use, and invalidate on success#

A token must stop working the moment it is used. When the password is changed:

• Mark that token used.
• Invalidate every other outstanding reset token for that account.
• Revoke existing sessions, or at least offer to, so an attacker who already had access is signed out.

Bind the token to the account#

Look up the account by the token's hash. Never accept a user ID or email from the URL or form alongside the token and trust it; a token for one account must not reset another.

Flow design#

Avoid account enumeration#

The reset request page should give the same response whether or not the address has an account:

If an account exists for that address, we have sent a password reset link.

Keep response timing similar too: perform the lookup and enqueue the email asynchronously so a real account does not respond measurably slower than a missing one.

Rate-limit requests#

Limit reset requests per account and per client IP. This stops attackers from flooding a user's inbox, and from using your reset form to send unwanted mail to arbitrary addresses, which also harms your sending reputation.

Do not trust the Host header#

A well-known class of bug builds the reset URL from the incoming request's Host header. An attacker who sends a reset request with a manipulated Host can cause your application to email a link pointing at their domain. If the victim clicks it, the token goes to the attacker. Build reset links from a configured, trusted base URL.

Keep the token out of logs and referrers#

• Do not log full reset URLs.
• On the reset page, set Referrer-Policy: no-referrer (or a strict policy) so the token is not leaked to third-party resources the page loads.
• Avoid loading third-party analytics scripts on the reset page entirely.
• After the token is validated, consider exchanging it for a short-lived server-side session and redirecting to a URL without the token.

Consider link scanners#

Corporate email security tools often fetch links in incoming mail to check them. If merely loading the reset URL consumes the token or changes the password, scanners will break your flow. Loading the link should show a form; the reset should happen only when the user submits it with a POST.

Handle lost access to the mailbox#

Reset by email assumes the user still controls their address. People leave jobs, let personal domains lapse, and lose access to old accounts. If the recovery path is "email only," an attacker who registers a lapsed domain can receive reset emails for every account tied to addresses at that domain. Mitigations include prompting users to confirm their email periodically, offering a second recovery factor for high-value accounts, and treating a recovery request after a long period of inactivity with extra scrutiny.