Two-Factor Authentication

Authenticator-app codes and backup codes on top of every sign-in method: turning it on, the user's setup, the sign-in step, limits and testing.

With two-factor authentication (2FA) on, a user can protect their account with an authenticator app (1Password, Google Authenticator, Authy…). After the first factor (password, magic link, email code or OAuth) they enter a 6-digit code, or one of their backup codes, before they get a session.

Turn It On

apps/web/.env

AUTH_TWO_FACTOR=true

Deployed: pnpm --filter web exec void secret put AUTH_TWO_FACTOR. No migration is needed: the tables (two_factor, user.two_factor_enabled) are always in the schema, so the flag only registers Better Auth's twoFactor plugin. With it off, its endpoints don't exist, /auth/two-factor answers 404, and /settings/security and its Settings → Security nav item stay (the sessions list), without the two-factor card.

The authenticator app labels the account with PRODUCT_NAME.

What Users See

Setting it up (/settings/security, Settings → Security in the account menu):

  1. Turn on, then the password (accounts without one skip this).
  2. A QR code, with the key to type in when scanning isn't possible.
  3. The first code from the app confirms it: 2FA is on. Every other session of that account is signed out (this browser stays signed in), so a session stolen before 2FA stops working (signOutOtherSessions, @kit/better-auth sessionGuards).
  4. Ten backup codes, shown only now, with Copy and Download. Each signs in once.

While an admin impersonates the user, every two-factor change answers 403: support never enrolls, turns off or regenerates codes for someone else. The same goes for the password, email, passkeys, linked accounts, sessions and account deletion (sessionGuards), and the security page says so instead of showing the forms.

New backup codes (with 2FA on) replace the old ones, which stop working. Turn off asks for the password the same way. Every change needs a sign-in from the last 10 minutes (FRESH_SESSION_MINUTES), for every account, password or not; an older session gets "sign in again" and a button that signs out and returns to the page. Better Auth only asks for the password, and only when the account has one, so without this a session left open, or stolen, could turn 2FA off or lock its owner out with an authenticator of its own.

Signing in: after the first factor the user lands on /auth/two-factor?next=…, enters the code (a pasted or autofilled code submits itself), or switches to a backup code, then continues to next.

Every Sign-In Method Is Challenged

Better Auth's plugin only challenges password sign-in. The kit also challenges every other way to sign in (EXTRA_CHALLENGE_PATHS in packages/better-auth/src/two-factor.ts):

Sign-inWhat happens
Password, email codeThe form gets twoFactorRedirect and goes to /auth/two-factor
Magic link, OAuthRedirected to /auth/two-factor?next=<where it was going>
OAuth with an ID token posted from the browser (/sign-in/social with idToken)Off by default (disableIdTokenSignIn); an app that turns it on gets twoFactorRedirect like the forms

A passkey sign-in is not challenged: the passkey is two factors itself (the device, and the PIN or biometrics the kit requires).

The session the first factor created is deleted before the response; the challenge lives in Better Auth's signed two_factor cookie. A new Better Auth plugin that signs users in must add its path there too (Adding Plugins).

Limits

Better Auth's own, kept as they are:

LimitValue
Requests to each /api/auth/two-factor/* endpoint3 every 10 seconds per IP
One challenge10 minutes and 5 wrong codes, then "Sign in again"
Wrong codes in a row, any factor10, then 2FA sign-in for that account is locked for 15 minutes

Secrets and backup codes are stored encrypted with BETTER_AUTH_SECRET; backup codes can't be read back from the browser (/two-factor/view-backup-codes is server-only), and neither can the secret (/two-factor/get-totp-uri answers 404: any session could copy the second factor with it). A code stays valid for its 30-second step and the ones either side, including after it was used: Better Auth doesn't refuse a replayed code.

Errors

The code's error codes map to messages in auth.errors (packages/i18n/src/messages/en/auth.json): INVALID_CODE, INVALID_BACKUP_CODE, INVALID_TWO_FACTOR_COOKIE (the challenge expired), TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE, ACCOUNT_TEMPORARILY_LOCKED, SESSION_NOT_FRESH, INVALID_PASSWORD.

Lost the Phone and the Codes

Users can't get in without a code, and the admin area has no action for this. Turn it off in the database yourself, in your database provider's SQL editor:

update "user" set two_factor_enabled = false where email = 'user@example.com';
delete from two_factor where user_id = (select id from "user" where email = 'user@example.com');

Do this only after confirming who's asking.

Anyone who knows a user's password can also use up their wrong-code budget and lock 2FA sign-in for that account for 15 minutes at a time (Better Auth's default).

Testing

packages/better-auth/src/__tests__/two-factor.test.ts walks every sign-in method for a user with 2FA on (password, email code, magic link, OAuth callback, OAuth ID token) and checks none gets a session without the code, plus backup codes, a wrong code, the limits (5 per sign-in, the account lock, the per-IP limit in two-factor-rate-limit.test.ts), the recent-sign-in rule and the unreadable secret and backup codes. E2E (apps/e2e/tests/auth/two-factor.spec.ts) sets it up from /settings/security, reading the key from the page and computing codes with totpCode() (tests/utils/auth.ts, Better Auth's own TOTP), then signs in with a password, a wrong code, a backup code and a magic link, replaces the backup codes, and turns it off.