Access
Two-factor sign-in
Protect accounts with a second factor: an authenticator app (TOTP), passkeys, or both, set up by each user in Settings → Security. A passkey can also sign in on its own, without the email or password.
Setting it up
In Settings → Security:
- Authenticator app: add it to any TOTP app (6 digits, 30-second steps), then confirm a code from it; it's on once confirmed. Each code works once.
- Passkeys: add one or more. Any authenticator the browser accepts will do.
With either, signing in with the password also takes a code or a passkey. Adding the first factor also makes recovery codes (below).
API tokens are unaffected: they're made by someone already signed in, and scripts can't answer a second factor.
Signing in
After the password, the sign-in page asks for a code from the app, a recovery code, or a passkey, within 5 minutes. A sign-in allows 5 wrong answers, then has to start over. Wrong answers also count as failed logins, so the password alone doesn't buy more guesses.
A passkey can also sign in on its own, without the email or password. It must verify you (PIN, biometrics), since it's the only factor.
Through the API, POST /api/auth/login answers
200 and the user when the account has no second factor. With one it
answers 202 and { mfa_token, totp, passkey } instead, and sets no
cookie. Then, within 5 minutes:
POST /api/auth/login/code{ mfa_token, code }: six digits from the app, or a recovery code;- or
POST /api/auth/passkey/options{ mfa_token }, thenPOST /api/auth/passkey/login{ mfa_token, credential }.
After 5 wrong answers it answers 410. Passwordless:
POST /api/auth/passkey/options {}, then POST /api/auth/passkey/login
{ credential }.
Passkeys
A passkey belongs to the address it was made on: one made on
panel.example.com doesn't work on another name for the panel. Passkeys
need HTTPS (or localhost) and a host name rather than an IP address.
Synced passkeys work; a key whose signature counter goes backwards is
refused, in case it was cloned.
Recovery codes
Ten codes, xxxxx-xxxxx, made with the first factor and shown once: keep
them somewhere safe. Each signs in once in place of a code or passkey.
Make new codes replaces them; removing the last factor deletes them.
Changing factors
Turning the app off, removing a passkey and making new recovery codes take the password (wrong ones count as failed logins), so a session left open somewhere isn't enough.
Lost access
An admin can Reset 2FA for another user on the Users page (PATCH /api/users/{id} { reset_two_factor: true }): their app, passkeys and
recovery codes go, and they sign in with the password alone until they set
them up again.