Second factor (authenticator app)

Sign-in with a password or an email code can be backed by a second factor: a 6 digit code from an authenticator app (TOTP, RFC 6238). Any standard app works.

Turn it on

1. Open Settings, Second factor and choose Set up authenticator.
2. Scan the QR code, or enter the key by hand.
3. Enter the 6 digit code the app shows. The second factor is now on.
4. Save the 10 recovery codes. They are shown once. Each works one time if you lose your phone.

Turning it on signs the account out of every other session, because those sessions were opened with one factor.

Signing in

After the password or the email code, the dashboard asks for the authenticator code. A recovery code can be entered in the same field. A code works once; reusing the code of the same 30 second step is refused.

Wrong codes count against the same limit as wrong passwords: 5 failures per email and 20 per client IP in 15 minutes. While locked, even the right code is refused until the window frees up.

Lost phone

Use a recovery code to sign in, then turn the second factor off and set it up again, or create new recovery codes. If you have neither, write to support from the address of the account. We will verify you before we reset it; this takes longer on purpose.

API behaviour

• POST /api/auth/verify-otp and POST /api/auth/login-password return {"mfa_required": true, "mfa_token": "...", "expires_in": 300} instead of a session when the account has a second factor. The token is only a challenge and cannot be used as a bearer.
• Send the token and the code to POST /api/auth/totp/verify to receive the session.
• Static admin tokens and workspace tokens (wm_team_…, wm_proj_…) are for machines and are not affected. A second factor belongs to a signed-in person.

curl -X POST https://app.example.com/api/auth/totp/verify \
  -H "Content-Type: application/json" \
  -d '{"mfa_token": "...", "code": "123456"}'

How secrets are stored

The shared secret is encrypted at rest. Recovery codes are stored only as hashes and removed when used. The server never shows the secret again after setup.