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 }, then POST /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.