Multi-factor authentication

What this means

Multi-factor authentication (MFA) adds a second step to sign-in: after your password, you also enter a 6-digit code from an authenticator app on your phone. The app generates a fresh code every 30 seconds.

Even if someone learns your password, they can't sign in without the phone - that's the point.

Bilbis uses TOTP (Time-based One-Time Password), the standard supported by Google Authenticator, 1Password, Authy, Microsoft Authenticator, and most other authenticator apps.

When MFA applies

If your role becomes one of the required roles after you've registered, the next sign-in routes you to enrollment instead of the dashboard.

Enrollment

The enrollment page walks through three steps.

Step 1 - Add Bilbis to your authenticator

The page shows a QR code and a long secret string. Open your authenticator app and either:

• Scan the QR code with your phone's camera in the app, or
• Tap "Enter manually" in the app and paste the secret.

Either way, your authenticator now knows about Bilbis and starts generating 6-digit codes that change every 30 seconds.

Step 2 - Save your recovery codes

Bilbis shows you a list of recovery codes. Save these. You can:

• Click Copy all to copy them to your clipboard.
• Click Download to save them as bilbis-recovery-codes.txt.

Each code works once. They're your fallback when you can't reach your authenticator app - for example, if your phone is lost, broken, or wiped.

Bilbis only shows the codes once. Save them somewhere durable: a password manager, a printed sheet, a secure note. Don't keep them only on the same phone that runs the authenticator app.

Step 3 - Confirm with a 6-digit code

Type the current 6-digit code from your authenticator into the Code input. Click Confirm and enable.

The page shows "Two-factor enabled" and routes you on - to your dashboard if you have one, or to the Workspace picker.

Voluntary enrollment

If your role doesn't require MFA but you want to add it anyway:

1. Sign in normally.
2. Go to Settings → Security.
3. Click Enable two-factor.
4. Walk through the same three steps.

Voluntary enrollment shows the same form without the "Required for admins" notice at the top.

Sign-in challenge

After enrollment, every sign-in goes through this:

1. Type your email and password as usual.
2. The challenge page asks for the current 6-digit code.
3. Type it. Click Verify.

The challenge page also has a Use a recovery code link if you can't reach your authenticator. Recovery codes are formatted like ABCD-1234-EFGH-5678. Each one consumes itself after use.

If you've used a recovery code, generate fresh ones in Settings → Security when you next sign in. The reminder appears in a toast.

Errors at the challenge

Disabling MFA

For voluntary users only - required-MFA roles can't disable.

1. Go to Settings → Security.
2. Click Disable two-factor.
3. The dialog asks for either a current 6-digit code or a recovery code.
4. Confirm.

After disabling, sign-in goes back to email + password only.

Switching authenticator apps

Bilbis doesn't have a "transfer" button. To switch:

1. Disable MFA in Settings → Security (voluntary users only).
2. Re-enroll. The QR code goes into the new authenticator.
3. Save fresh recovery codes.

For required-MFA roles, this isn't allowed - your operator has to reset MFA on your account first.

Lost authenticator + lost recovery codes

Without your authenticator and without recovery codes, you're locked out. The Bilbis app cannot recover this - only your operator can. Contact your admin or the Bilbis operator to reset MFA on your account. After they reset it, you'll re-enroll on the next sign-in.

Where MFA shows up

Permissions

Problems and fixes

Related pages

• Sign in and register - the password step that comes before MFA.
• Password reset - different flow; MFA still applies after a reset.
• Invitations - MFA still applies after accepting an invite.