Two-Factor Authentication

auth.twoFactor enables TOTP-based two-factor authentication (time-based one-time passwords). Users add a second factor with an authenticator app (Google Authenticator, 1Password, Authy, …) and enter a rotating code at sign-in.

auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true

2FA requires the emailAndPassword strategy. TOTP layers a second factor on top of password sign-in. Configuring twoFactor without an emailAndPassword strategy in auth.strategies fails validation at startup.

Enabling 2FA

The simplest form is a boolean — enable with defaults:

auth:
  strategies:
    - type: emailAndPassword
  twoFactor: true

For control over the issuer name, backup codes, and code format, use the object form:

auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
    digits: 6
    period: 30

Configuration

auth.twoFactor accepts either a boolean or a configuration object.

Property	Description
(boolean)	`true` enables 2FA with defaults; `false` (or omitting the field) disables it.
`issuer`	Name shown in the user's authenticator app (e.g. `MyApp`). Identifies the account entry.
`backupCodes`	Boolean. When `true`, generate single-use backup codes for account recovery.
`digits`	Number of digits in the TOTP code, 4–8. Defaults to `6`.
`period`	Code rotation interval in seconds (positive). Defaults to `30`.

Keep digits: 6 and period: 30 unless you have a specific compatibility need — they match the defaults nearly every authenticator app expects. Non-standard values can confuse some apps.

Backup Codes

When backupCodes: true, users receive a set of single-use recovery codes during 2FA enrollment — essential when they lose access to their authenticator device. Delivery is customizable via the twoFactorBackupCodes email template:

auth:
  strategies:
    - type: emailAndPassword
  twoFactor:
    issuer: MyApp
    backupCodes: true
  emailTemplates:
    twoFactorBackupCodes:
      subject: Your MyApp recovery codes
      text: 'Keep these recovery codes safe: $code'

Enrollment Flow

The user signs in with email and password as usual.
They enroll in 2FA — the app shows a TOTP secret (typically as a QR code) labeled with issuer.
They scan it into an authenticator app, which begins generating codes every period seconds.
On subsequent sign-ins, after the password step they enter the current digits-length code.
If enabled, backup codes provide a recovery path when the device is unavailable.

Strategies — the emailAndPassword strategy 2FA depends on, plus the twoFactorBackupCodes email template.
Sessions — sessions issued after the second factor succeeds.
Authentication Overview — the auth block in context.

← PreviousSessions Next →OAuth Server