Two-factor authentication

Two-factor authentication (2FA) adds a six-digit code from an authenticator app to every password sign-in.

Setting it up (web)

1. Settings, Security, Enable two-factor. (POST /api/auth/2fa/setup returns the secret and a QR code.)
2. Scan the QR code with an authenticator app (any TOTP app: 1Password, Google Authenticator, Authy and others).
3. Enter the current code to confirm (POST /api/auth/2fa/verify-setup).
4. Save the eight recovery codes shown once. Each works one time, in place of a code, if you lose the device.

Setup is web-only. In the app, Account, More tools opens the web dashboard with your session for it.

Signing in with it on

• Web: password, then the code.
• iOS: password, then a code sheet. A recovery code works in the same field.
• API: POST /api/auth/login returns a 2FA challenge; POST /api/auth/2fa/verify completes it. API keys are not affected: a key is its own credential.
• Sign in with Apple: Apple's own two-factor stands in; DomainGuard's TOTP applies to password sign-ins.

Status and disabling

GET /api/auth/2fa/status reports whether it is on. Disable from Settings, Security with a current code (POST /api/auth/2fa/disable). The secret is stored encrypted at rest.

Lost the device

Use a recovery code to sign in, then disable and re-enable 2FA to get a new secret and fresh codes. Out of recovery codes: Ask for help from the locked-out sign-in screen; identity is verified before anything is reset.

Common questions

The code is refused. Check the phone's clock is set automatically; TOTP is time-based. A code is valid for its 30-second window plus a small tolerance.

Does 2FA lock the API? No. Keys bypass it, which is why keys are scoped and can expire.

Does the QR handoff bypass it? The handoff is created from an already-authenticated web session, so the second factor was already satisfied there.