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

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

:::callout
**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:

```yaml
auth:
  strategies:
    - type: emailAndPassword
  twoFactor: true
```

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

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

:::callout
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](/en/docs/auth-strategies#email-templates):

```yaml
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

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

## Related Pages

- [Strategies](/en/docs/auth-strategies) — the `emailAndPassword` strategy 2FA depends on, plus the `twoFactorBackupCodes` email template.
- [Sessions](/en/docs/auth-sessions) — sessions issued after the second factor succeeds.
- [Authentication Overview](/en/docs/auth-overview) — the `auth` block in context.