# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/two-factor*

---

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

```bash {% title="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](https://www.better-auth.com/docs/plugins/2fa). 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`.

{% callout type="warning" %}
Turning the flag off again drops the protection: users who set up 2FA sign in with the first factor alone, and the Security page no longer shows the two-factor card, so they can't see it. Their setup stays in the database and works again when the flag is back on.
{% /callout %}

## 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-in | What happens |
|---|---|
| Password, email code | The form gets `twoFactorRedirect` and goes to `/auth/two-factor` |
| Magic link, OAuth | Redirected 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](./passkeys) 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](./adding-plugins)).

## Limits

Better Auth's own, kept as they are:

| Limit | Value |
|---|---|
| Requests to each `/api/auth/two-factor/*` endpoint | 3 every 10 seconds per IP |
| One challenge | 10 minutes and 5 wrong codes, then "Sign in again" |
| Wrong codes in a row, any factor | 10, 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:

```sql
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.
