Save these codes in a secure location:
{codes.map((code, i) => (
- {code}
))}
);
};
```
### Regenerating Backup Codes
When users need new codes, regenerate them (this invalidates all previous codes):
```ts
const regenerateBackupCodes = async (password: string) => {
const { data, error } = await authClient.twoFactor.generateBackupCodes({
password,
});
// data.backupCodes contains the new codes
};
```
### Using Backup Codes for Recovery
```ts
const verifyBackupCode = async (code: string) => {
const { data, error } = await authClient.twoFactor.verifyBackupCode({
code,
trustDevice: true,
});
};
```
**Note**: Each backup code can only be used once and is removed from the database after successful verification.
### Backup Code Configuration
```ts
twoFactor({
backupCodeOptions: {
amount: 10, // Number of codes to generate (default: 10)
length: 10, // Length of each code (default: 10)
storeBackupCodes: "encrypted", // Options: "plain", "encrypted"
},
});
```
## Handling 2FA During Sign-In
When a user with 2FA enabled signs in, the response includes `twoFactorRedirect: true`:
```ts
const signIn = async (email: string, password: string) => {
const { data, error } = await authClient.signIn.email(
{
email,
password,
},
{
onSuccess(context) {
if (context.data.twoFactorRedirect) {
// Redirect to 2FA verification page
window.location.href = "/2fa";
}
},
}
);
};
```
### Server-Side 2FA Detection
When using `auth.api.signInEmail` on the server, check for 2FA redirect:
```ts
const response = await auth.api.signInEmail({
body: {
email: "user@example.com",
password: "password",
},
});
if ("twoFactorRedirect" in response) {
// Handle 2FA verification
}
```
## Trusted Devices
Trusted devices allow users to skip 2FA verification on subsequent sign-ins for a configurable period.
### Enabling Trust on Verification
Pass `trustDevice: true` when verifying 2FA:
```ts
await authClient.twoFactor.verifyTotp({
code: "123456",
trustDevice: true,
});
```
### Configuring Trust Duration
```ts
twoFactor({
trustDeviceMaxAge: 30 * 24 * 60 * 60, // 30 days in seconds (default)
});
```
**Note**: The trust period refreshes on each successful sign-in within the trust window.
## Security Considerations
### Session Management
During the 2FA flow:
1. User signs in with credentials
2. Session cookie is removed (not yet authenticated)
3. A temporary two-factor cookie is set (default: 10-minute expiration)
4. User verifies via TOTP, OTP, or backup code
5. Session cookie is created upon successful verification
Configure the two-factor cookie expiration:
```ts
twoFactor({
twoFactorCookieMaxAge: 600, // 10 minutes in seconds (default)
});
```
### Rate Limiting
Keep endpoint rate limiting enabled. Add `allowedAttempts` to the existing
`otpOptions` configuration that already supplies `sendOTP`; it limits guesses
against one issued OTP code. Better Auth 1.7 also supports account-level
lockout across TOTP, OTP, and backup-code failures:
```ts
twoFactor({
otpOptions: {
allowedAttempts: 5,
},
accountLockout: {
enabled: true,
maxFailedAttempts: 10,
durationSeconds: 15 * 60,
},
});
```
A successful second-factor verification resets the account counter. Locked attempts return `429` with `ACCOUNT_TEMPORARILY_LOCKED`. Endpoint throttling, per-code attempt limits, and account lockout are separate controls.
### Encryption at Rest
- TOTP secrets are encrypted using symmetric encryption with your auth secret
- Backup codes are stored encrypted by default
- OTP codes can be configured for plain, encrypted, or hashed storage
### Constant-Time Comparison
Better Auth uses constant-time comparison for OTP verification to prevent timing attacks.
### Credential Account Requirement
By default, enabling and managing 2FA requires a credential account. Set `allowPasswordless: true` only when the product intentionally allows passwordless users to manage 2FA; a password remains required whenever the user has a credential account. This option does not make OAuth or other passwordless sign-in endpoints pass through the 2FA challenge automatically.
## Disabling 2FA
Allow users to disable 2FA with password confirmation:
```ts
const disable2FA = async (password: string) => {
const { data, error } = await authClient.twoFactor.disable({
password,
});
};
```
**Note**: When 2FA is disabled, trusted device records are revoked.
## Complete Configuration Example
```ts
import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";
import { sendEmail } from "./email";
export const auth = betterAuth({
appName: "My App",
plugins: [
twoFactor({
// TOTP settings
issuer: "My App",
totpOptions: {
digits: 6,
period: 30,
},
// OTP settings
otpOptions: {
sendOTP: async ({ user, otp }) => {
await sendEmail({
to: user.email,
subject: "Your verification code",
text: `Your code is: ${otp}`,
});
},
period: 5,
allowedAttempts: 5,
storeOTP: "encrypted",
},
accountLockout: {
enabled: true,
maxFailedAttempts: 10,
durationSeconds: 15 * 60,
},
// Backup code settings
backupCodeOptions: {
amount: 10,
length: 10,
storeBackupCodes: "encrypted",
},
// Session settings
twoFactorCookieMaxAge: 600, // 10 minutes
trustDeviceMaxAge: 30 * 24 * 60 * 60, // 30 days
}),
],
});
```