Two-Factor Authentication

NuxtBase supports TOTP-based two-factor authentication with backup codes.

This feature is managed from the dashboard security settings, not the login page itself. The login page only handles the challenge after the account already has 2FA enabled.

Where 2FA Lives in the Product

There are two distinct parts:

1. setup and disable flows in dashboard settings
2. challenge flow during login

That separation is useful when you are debugging, because “I cannot log in” and “I cannot enable 2FA” are different problems in this template.

Enabling 2FA

For credential users, the setup flow is:

1. open dashboard settings
2. open the security card
3. click Enable Two-Factor
4. confirm with the account password
5. scan the QR code or copy the secret
6. save the backup codes
7. enter the 6-digit verification code

The UI explicitly presents the setup in three stages:

• scan
• backup codes
• verify

Backup Codes

Backup codes are generated as part of setup and displayed immediately in the modal.

The user can also download them as a text file.

This is important enough to call out because backup codes are part of the primary shipped UX, not an afterthought hidden in developer tools.

OAuth-Only Accounts

NuxtBase treats OAuth-only accounts differently from accounts that also have a credential login.

For OAuth-only users:

• enabling 2FA skips password confirmation
• the app creates a fresh TOTP setup through a dedicated route
• disabling 2FA uses a 6-digit verification code instead of password confirmation

This is a good example of the template handling a real product edge case instead of assuming every user has a password.

Login Challenge Flow

When a user with 2FA enabled signs in with email and password:

1. the initial sign-in succeeds far enough to indicate a 2FA challenge is required
2. the login page opens an in-page modal
3. the user chooses either:
   • authenticator code
   • backup code
4. the user can also choose to trust the device

After successful verification, the user is redirected to the intended in-app destination.

Validation Rules

The settings-side verification schema expects:

• exactly 6 digits for TOTP verification

The login challenge also normalizes entered digits before verification.

What To Verify

1. enable 2FA on a password-based account
2. save and test at least one backup code
3. sign out and sign back in
4. complete the TOTP challenge on the login page
5. repeat with a backup code
6. if relevant, test enable/disable behavior on an OAuth-only account

Caution

If you customize the settings UI, do not remove the backup-code step or the login challenge mode switch unless you are intentionally replacing that behavior.