Two-factor (TOTP) for admin accounts

Admin accounts (super, ops, content, financial) can require a second factor at sign-in: a 6-digit TOTP code from an authenticator app. An Admin password or passkey gates the first factor; TOTP gates protected Admin routes.

This article walks through enrolment, daily use, and recovery.

When you'll be prompted

TOTP is policy-driven per admin tier. Super admins can flip the requirement for any tier via Admin → Team → TOTP policy. The two relevant gates:

• totpRequired = true AND not yet enrolled — the Admin app redirects protected requests to /2fa-required until you enrol.
• Enrolled AND no fresh re-auth cookie — the proxy redirects sensitive admin actions to /2fa-verify to re-confirm. Cookie defaults to 8 hours.

Non-required tiers can still enrol voluntarily — the profile card nudges them.

Enrolling

1. Open Settings → Security → Two-factor (TOTP).
2. Tap Set up two-factor.
3. Scan the QR with an authenticator app — Google Authenticator, Authy, 1Password, Bitwarden, anything that follows TOTP (RFC 6238). The on-screen secret is also typed-in-able if you can't scan.
4. Enter the 6-digit code your app shows. The first valid code confirms enrolment.
5. Save your 10 backup codes. Print them, take a screenshot, paste into a password manager — anywhere not the device you're enrolling on. They show exactly once; we can't display them again.

That's it. From the next login onwards, you'll be asked for a code after your password or passkey is verified.

Daily use

• Sign in to the Admin console with a password or passkey, then complete the TOTP step when prompted.
• TOTP codes refresh every 30 seconds. We accept codes that are 1 step old or 1 step ahead to forgive clock drift.
• After 10 wrong attempts in 5 minutes, the verify endpoint rate-limits — wait the cooldown out and try again.

Backup codes

Each backup code is a one-time use string of letters/digits. Use them when you don't have the authenticator app on hand:

1. Log in normally with your password or passkey → TOTP prompt.
2. Tap Use a backup code instead.
3. Paste any of your 10 codes. It's consumed on use.

After consuming a code, the count on Settings → Security drops by 1. When you're down to 2-3 codes, the surface flashes a warning — tap Regenerate backup codes to mint a fresh set of 10 (invalidates the old ones, including the unused ones).

Recovery — phone lost

If you've lost the device with your authenticator app AND can't reach your backup codes:

1. Open the Admin console sign-in page and authenticate with your password or passkey.
2. Email hello@keybaki.com from the email tied to your account, with TOTP reset in the subject. A super admin can clear your TOTP enrolment so you can re-enrol on the new device. Plain teachers / parents / students never have TOTP enrolled, so this only applies to admins.

The reset action lives at Admin → Team → [user] for super-tier admins helping their teammates. It logs an audit row + sends an SMS notification to the affected admin's phone.

Common issues

• "Invalid code" with the right code. Phone clock drift. Open phone Settings → Date & time → enable "Set automatically". Re-try.
• "Too many attempts." Rate-limit cooldown. Wait 5 minutes and try again. If you're locked out and time-pressured, use a backup code.
• Regenerate burned my codes too soon. The new set replaces the old set — every old code is invalid. Save the new ones somewhere durable.
• Want to disable TOTP entirely. Settings → Security → Two-factor (TOTP) → Disable. Requires a re-auth + confirmation. Note: if totpRequired is on for your tier, disabling locks you out of /admin/* until you re-enrol.