twoFactor() plugin adds TOTP (time-based one-time password) support compatible with Google Authenticator, Authy, 1Password, and any RFC 6238 app. Users enroll once by scanning a QR code, then provide a 6-digit code as a second factor.
theAuth stores and verifies the TOTP secret and backup codes. It does not sit inside your sign-in flow: there is no built-in “two factor required” challenge on the primary sign-in endpoints. You decide in your own sign-in code when to ask for a code, and call the verify endpoint (or theauth.totp.verify) to check it.
Setup
2
Add the plugin
lib/theauth.ts
auth.adapter or an auth.session token (Authorization: Bearer header or the theauth_session cookie). twoFactor() works with any primary auth method.Instead of the plugin you can pass the same options as a top-level totp key to createTheAuth. That exposes theauth.totp (setup, enable, verify, disable, isEnabled, regenerateBackupCodes, handleRequest), which is null when the key is absent. The module’s own handleRequest serves POST /auth/2fa/setup, /enable, /verify, /disable and /backup-codes with a userId in the body and no session check, so call the methods from server code rather than exposing that handler to browsers.Enrollment flow
All plugin endpoints require an authenticated request.1
Generate a TOTP secret
POST /auth/2fa/enrolluri (an otpauth:// URL) as a QR code in your UI with a QR library of your choice. The user scans it with their authenticator app, or enters secret manually. Show backupCodes once at this point. Only hashes are stored, so they cannot be retrieved again. Calling enroll again replaces the secret and backup codes and turns 2FA off until the new secret is confirmed.Checking a code at sign-in
Once 2FA is enabled, the same endpoint checks a code for the authenticated user:POST /auth/2fa/verify
{ valid: boolean, usedBackupCode?: boolean }. A wrong code returns 200 with valid: false, so check the field rather than the status. The endpoint does not issue a session or set a cookie. To gate sign-in, complete the primary sign-in on your server, hold the user in a “pending second factor” state of your own, and call theauth.totp.verify(userId, code) before treating them as signed in.
Codes are accepted within one 30-second step either side of the current time by default (window and period options).
Backup codes
Ten single-use backup codes are generated at enrollment (backupCodeCount). Each is an 8-character code from an alphabet that leaves out 0, O, 1 and I. A backup code can be submitted in place of a TOTP code at the verify and disable endpoints, useful when the user has lost access to their authenticator app. A used backup code cannot be reused, and the response reports usedBackupCode: true.
Regenerate backup codes
POST /auth/2fa/backup-codes
This invalidates all existing backup codes and issues a new set. It requires a valid TOTP or backup code in the body as confirmation.
Disabling 2FA
POST /auth/2fa/disable
Requires a valid TOTP or backup code as confirmation. Disabling deletes the stored secret and backup codes:
Check enrollment status
GET /auth/2fa/status
Endpoints
All endpoints require an authenticated request.Options
Related
Trusted devices
Skip 2FA on verified devices for a limited window.
Password breach checking
Block passwords found in known data breaches at sign-up.
Username and password
Built-in primary auth method that pairs with two-factor auth.
Passkey
Phishing-resistant WebAuthn alternative to TOTP.