Password Reset

Allow users to reset forgotten passwords via secure email links in your Next.js SaaS application.

Users self-recover forgotten passwords via secure email links. Enter email, receive link, set new password. Works out of the box with your configured mailer.

This page is part of the Authentication documentation.

The password reset flow lets users recover access when they forget their password. From the sign-in page, users click "Forgot your password?" and enter their email. Better Auth sends a time-limited reset link. Clicking the link takes them to a form where they set a new password (subject to your password requirements). The flow is pre-built and uses your configured mailer.

Password reset is the self-service flow where users request a time-limited email link to set a new password without admin intervention.

Password Reset Flow

1. Request Reset

User clicks "Forgot your password?" on the sign-in page.

  • Location: apps/web/app/[locale]/auth/password-reset/page.tsx
  • Route: /auth/password-reset

User enters their email address. The system always shows a success message, even if the email doesn't exist. This prevents attackers from discovering which emails are registered (email enumeration protection).

2. Email Sent

If the email exists, Better Auth sends a password reset email with a secure link. The link contains a cryptographically signed token.

3. Set New Password

User clicks the link in their email and is taken to the reset form.

  • Location: apps/web/app/[locale]/(public)/password-reset/page.tsx
  • Route: /password-reset (with token in query params)

The new password must meet your configured requirements (length, special characters, etc.). After successful reset, the user is redirected to sign in with their new password.

Email Template

Customize the password reset email at:

packages/email-templates/src/emails/password-reset.email.tsx

The template receives the reset URL and user information. It supports i18n and custom styling with React Email.

For mailer configuration, see Email Configuration.

Security Features

Token Expiration

Reset links expire after a configurable time window (typically 1 hour). This limits the window for link interception.

Single Use

Each reset link can only be used once. After a successful reset, the token is invalidated. Requesting a new link also invalidates previous ones.

Rate Limiting

Password reset requests are rate-limited to prevent abuse. Attackers can't flood a user's inbox or probe for valid emails at scale.

Email Enumeration Protection

The same success message is shown whether the email exists or not. Attackers can't determine which emails are registered by observing response differences.

Token Security

Reset tokens are cryptographically signed by Better Auth using your BETTER_AUTH_SECRET. Tokens can't be forged or tampered with.

Password Requirements

The new password must meet the same requirements as registration:

apps/web/.env.local

NEXT_PUBLIC_PASSWORD_MIN_LENGTH=8
NEXT_PUBLIC_PASSWORD_MAX_LENGTH=99
NEXT_PUBLIC_PASSWORD_REQUIRE_SPECIAL_CHARS=true
NEXT_PUBLIC_PASSWORD_REQUIRE_NUMBERS=true
NEXT_PUBLIC_PASSWORD_REQUIRE_UPPERCASE=true

The reset form displays these requirements as the user types.

Session Handling After Reset

After a successful password reset:

  1. The reset token is invalidated
  2. The user is redirected to sign in
  3. Existing sessions remain valid by default

To invalidate all sessions after password reset (forcing re-authentication on all devices), customize the reset handler to revoke sessions.

Admin-Initiated Reset

Admins can trigger password reset emails for users via the admin panel. They cannot set passwords directly for security reasons. The user still goes through the standard email verification flow.

Common Pitfalls

  • Email not configured: Reset emails won't send without a working mailer. Test email delivery first with Email Configuration.
  • Reset link in spam: Users may not find the email. Advise checking spam folders in the UI message.
  • Expired links without clear feedback: If the link expired, the form shows a clear message with a "request new link" option. Test this flow.
  • Not testing the full flow: Request reset, receive email, click link, enter new password, sign in. Test the entire chain.
  • Assuming reset invalidates sessions: By default, existing sessions remain valid. If this is a security requirement, customize the handler.
  • OAuth users trying password reset: Users who signed up with OAuth don't have a password. The reset flow won't work for them. They should use OAuth sign-in.

Frequently Asked Questions

How long is the reset link valid?
Reset links typically expire after 1 hour. This is configurable in the Better Auth configuration.
What if the user never receives the email?
Check mailer configuration, spam folders, and email delivery logs. The email may be blocked by the recipient's email server or caught by spam filters.
Can I add security questions to password reset?
Not out of the box. You would need to customize the reset flow to add additional verification steps before sending the reset link.
Are existing sessions invalidated after reset?
By default, existing sessions remain valid. To invalidate them, customize the reset success handler to revoke all user sessions.
Can admins reset user passwords?
Admins can trigger password reset emails via the admin panel. They cannot set passwords directly, which prevents insider attacks.
What happens if a user clicks an old reset link?
The link is invalid. Reset tokens are single-use and expire. The user sees an error message and can request a new link.

Next: Session Handling