title: "Two-factor authentication" description: "Enable TOTP-based 2FA on your BoxWatch account." last_updated: "2026-05-24"

Two-factor authentication

BoxWatch supports TOTP-based two-factor auth using any standard authenticator app. Enable it, save your recovery codes, and your account is protected against password-only compromise.

Set up 2FA

1. Go to Dashboard → Account → Security → Enable 2FA.
2. BoxWatch shows a QR code and a list of 8 recovery codes. Scan the QR with your authenticator app.
3. Save the recovery codes somewhere safe before continuing — a password manager, an encrypted note, or printed and locked in a drawer. They're shown once.
4. Enter the 6-digit code from your authenticator to confirm. 2FA is now active.

The QR code encodes an otpauth:// URL — if you can't scan it, your app will accept the secret as a manual entry.

Compatible apps

Any RFC 6238 TOTP app:

• 1Password
• Bitwarden
• Authy
• Google Authenticator
• Microsoft Authenticator
• Aegis (Android)
• Raivo (iOS)

Logging in with 2FA

On login, after your password is accepted, BoxWatch prompts for your 6-digit code. The API returns requires_2fa: true on the first response, then accepts a second request that includes the code:

curl -X POST https://api.boxwatch.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"…","two_factor_code":"123456"}'

Or use a recovery code instead:

curl -X POST https://api.boxwatch.app/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"…","recovery_code":"ABCD1234EF"}'

Each recovery code is single-use. After a code is consumed, the remaining list shrinks by one. You started with 8; once you're down to 0, you can't use codes again until you regenerate them.

Regenerate recovery codes

If you've used most of your codes, or you suspect they leaked:

Dashboard → Account → Security → Regenerate recovery codes

You'll need to enter a fresh TOTP code to confirm. BoxWatch issues 8 new codes; the previous batch is invalidated immediately.

Disable 2FA

Dashboard → Account → Security → Disable 2FA. Requires a valid TOTP code to confirm — you can't disable 2FA with just your password.

Body: { "code": "123456" }.

After disabling, your secret and recovery codes are wiped from the database. Re-enabling generates a fresh secret and fresh codes.

Lost your device

Use a recovery code to log in:

1. Click "Use a recovery code" on the 2FA prompt.
2. Enter one of the codes from your saved list.
3. You're in. The code is now consumed.

Once logged in, regenerate recovery codes (which requires a TOTP code, which you don't have — so first disable 2FA with a recovery-code-authenticated session, then re-enable from scratch on your new device).

If you've lost both your authenticator and your recovery codes, email [email protected] from the account email. Support disabling 2FA requires identity verification — expect a slow, manual process.

2FA and API keys

API keys are independent of 2FA. A request authenticated by a bearer token isn't prompted for a TOTP code — keys are their own credential. If you rely heavily on the API, rotate keys aggressively and protect them like passwords. See API keys.

See also

• Account overview
• API keys