Password Reset Flow#

The password reset flow is handled by three endpoints in packages/better-auth/src/api/routes/password.ts and is activated only when emailAndPassword.sendResetPassword is configured.

Endpoints#

Step-by-Step Flow#

1. Request (POST /request-password-reset)#

Accepts { email, redirectTo? } 1.

• Enumeration protection: if the user is not found, the handler still calls generateId(24) and a dummy DB lookup to equalize timing before returning a generic success message 2.
• Generates a 24-character random token via generateId(24) 3.
• Stores the token in the verification table under the key reset-password:{token}, with the user's ID as the value and a configurable TTL (default: 1 hour) 4.
• The configurable expiry is emailAndPassword.resetPasswordTokenExpiresIn (in seconds) 5.
• Calls emailAndPassword.sendResetPassword({ user, url, token }, request) in the background 6. The url embeds the token and the encoded redirectTo as callbackURL.

2. Callback (GET /reset-password/:token)#

Reads the verification row for reset-password:{token} and checks expiresAt 7.

• Expired or missing tokens redirect to callbackURL?error=INVALID_TOKEN.
• Valid tokens redirect to callbackURL?token={token}.

Note: This GET endpoint does not consume the token. It only validates expiry and redirects. Token consumption happens in the POST below.

3. Reset (POST /reset-password)#

Accepts { newPassword, token } (token can also come from ?token query param) 8.

• Password length is validated against minPasswordLength / maxPasswordLength 9.
• Atomic single-use consumption: calls internalAdapter.consumeVerificationValue("reset-password:{token}") — this atomically deletes and returns the row 10. The first concurrent caller wins; any racer (or expired token) gets null → BAD_REQUEST INVALID_TOKEN.
• On success: hashes the new password and either creates a credential account (if none exists) or updates the existing one 11.
• Post-reset hooks (configuration-driven):
  • emailAndPassword.onPasswordReset({ user }, request) fires if configured 12.
  • emailAndPassword.revokeSessionsOnPasswordReset = true deletes all sessions for the user after a successful reset 13.

Single-Use Token Guarantee#

Token consumption uses consumeVerificationValue — the higher-level atomic primitive built on consumeOne. It deletes-and-returns the row in a single atomic operation; a racer getting null is rejected immediately. Tokens past expiresAt are still deleted on consumption (no replay possible) but null is returned to the caller.

Plugin Hook Architecture#

Password reset handlers participate in the standard request lifecycle hook pipeline: runBeforeHooks → handler → runAfterHooks via dispatchAuthEndpoint. Plugins can intercept both /request-password-reset and /reset-password using the standard hooks.before / hooks.after matcher pattern 14.

Example — haveIBeenPwned plugin 15: Rather than a hooks.before route matcher, this plugin overrides the ctx.password.hash function in its init() hook. When any endpoint on the default path list (including /reset-password) calls password.hash(), the wrapper intercepts it, sends the SHA-1 prefix to api.pwnedpasswords.com using k-anonymity, and throws PASSWORD_COMPROMISED before the hash ever completes 16. This blocks a compromised new password before the credential is written.

Plugins can also intercept via hooks.before to short-circuit or mutate context, or hooks.after to react to the successful reset (e.g., audit logging). See Request Lifecycle Hooks for the full pattern.

Alternative Reset Mechanisms#

The core flow above is email-link-based. Two plugins provide OTP-based alternatives on the same general structure:

• emailOTP plugin — POST /email-otp/request-password-reset + POST /email-otp/reset-password 17
• phoneNumber plugin — POST /phone-number/request-password-reset + POST /phone-number/reset-password 18

Both use atomicVerifyOTP / consumeVerificationValue for the same single-use guarantee.

Key Source Files#