Skip to main content

Set up 2FA

Two-factor authentication via TOTP (Time-based One-Time Password). Works with Google Authenticator, Authy, 1Password, Bitwarden, etc.

Enrol​

Sidebar → Settings → Two-Factor Authentication card → Enable.

You'll see:

  1. A QR code + a text secret (in case the QR doesn't scan)
  2. A verification code input
  3. A save button

Steps:

  1. Open your authenticator app
  2. Add a new entry — scan the QR or paste the text secret
  3. The app starts showing a 6-digit code that rotates every 30s
  4. Type the current code into the verification input
  5. Save

If the code is rejected, your phone clock might be drifting — check your device's "set automatically" time setting. TOTP allows ± 30 seconds of drift; more than that and the code won't match.

What happens on next login​

After Enable, every login asks you for:

  1. Email + password (same as before)
  2. The current 6-digit TOTP

Without the second factor you can't sign in.

If 2FA is required by policy​

Your admin may have flipped the Two-factor authentication required setting. In that case:

  • Existing users who haven't enrolled get prompted to enrol during their next login (mid-flow setup)
  • New users see the enrolment step right after they accept their invitation

You can still skip the prompt and log in once during a grace window, but every subsequent login will block until you enrol.

Disable 2FA​

Settings → Two-Factor Authentication card → Disable → confirm.

You'll be asked for your current TOTP code as the confirmation — to make sure someone with your password but not your phone can't turn it off.

If 2FA is required by policy, you can't disable it for yourself. Talk to your admin if your authenticator device is lost.

Lost your authenticator device​

Two paths:

Self-service via recovery codes​

If your install issues recovery codes (some do, some don't — check your Settings page), you saved them when enrolling. Use one to sign in: at the 2FA prompt, click "Use recovery code" → paste one of the saved codes. Each code is single-use.

After signing in, immediately enrol a fresh authenticator: disable 2FA → enable again → scan the new QR.

Admin reset​

If you don't have recovery codes, ask your admin: they can do an Admin → Users → Reset 2FA for your account. After the reset you log in with just password and re-enrol on the spot.

Why TOTP and not SMS / email​

Short answer: SMS is phishable + SIM-swappable; email-as-second- factor is just a worse second password. TOTP is offline (no network round-trip), uses a shared secret, and is the standard recommendation for 2FA.

We don't currently support U2F / WebAuthn / hardware keys. If you need that, file a feature request.

Common errors​

  • INVALID_2FA_CODE — wrong code or clock drift
  • 2FA_REQUIRED — server policy says you must enrol; the login flow will redirect you to setup
  • TOTP code suddenly stops working — phone clock drifted

    30s, or someone restored a phone backup that re-keyed the authenticator app. Use a recovery code or ask admin to reset.

See also​