Two-factor authentication (MFA)
Protect your SlugBase account with TOTP authenticator codes and one-time backup codes, including setup, sign-in, recovery, and how API tokens behave.
What this is for
Two-factor authentication (MFA) adds a second step after your password or OIDC sign-in: a 6-digit code from an authenticator app (TOTP), or a backup code if you cannot use the app. You turn it on from Profile and manage backup codes there while you are signed in.
Your deployment can set MFA_ISSUER_NAME so the account label in your authenticator app matches your instance (for example your organization name). If it is unset, entries typically show SlugBase.
Before you start
- You need an authenticator app (for example Google Authenticator, 1Password, Authy, or similar).
- You must already be signed in to Profile to start enrollment.
Turn on MFA
Open Profile
From the user menu, open Profile. Find the Multi-factor authentication (or equivalent) section.
Start setup
Choose the control to enable or set up MFA. The app asks the server to begin enrollment.
Add the account to your app
Scan the QR code with your authenticator app, or enter the manual secret if you cannot scan. The secret is shown only during setup—your app stores it locally.
Confirm with a code
Enter a valid 6-digit code from the app to confirm. After confirmation, MFA is on for your account.
Save your backup codes
The app shows a set of one-time backup codes (plain text) once. Store them in a safe place (password manager, printed copy in a secure location). Each code works a single time if you lose access to your authenticator.
If you started setup by mistake, use Cancel setup (or equivalent) on Profile so the server clears an unfinished enrollment. You can start again later.
Sign in with MFA
- Sign in with email and password or your OIDC provider as usual.
- If MFA is enabled, you are prompted for a 6-digit code (or you land on the MFA challenge screen after OIDC).
- Enter a code from your authenticator, or a backup code instead.
- After a successful code, you receive a normal signed-in session.
Wrong passwords behave like today: you do not get a hint that the account has MFA until the first factor succeeds.
Recovery and lockout
| Situation | What to do |
|---|---|
| Authenticator unavailable, backup codes available | Sign in with a backup code instead of the 6-digit TOTP. That code is consumed and cannot be reused. |
| Signed in, need new backup codes | On Profile, use Regenerate backup codes (you confirm with your password if you have one, and a valid TOTP or unused backup code—same trust level as turning MFA off). Save the new list; old codes stop working. |
| Lost authenticator and all backup codes | SlugBase does not send an automated email unlock. Contact whoever runs your instance (self-hosted: your administrator; they can reset MFA in the database—see internal operator docs). |
Treat backup codes like passwords. Anyone with a unused backup code can complete MFA for your account until that code is used or regenerated.
API tokens and MFA
Personal API tokens (the sb_… secrets you create under Developer / API Access on Profile) authenticate REST API requests as you. They follow a personal access token model: possession of the token is sufficient. Interactive MFA is not required when using a valid API token, even if your account has MFA enabled for browser login.
For creating and revoking tokens, see API tokens.
Turn off MFA
On Profile, use the flow to disable MFA. You must prove you still control a factor: typically password (if your account has one) plus a valid TOTP or unused backup code. OIDC-only accounts follow the in-app wording (code without password).
Disabling MFA removes backup codes for that account; you can enroll again later.
Related
Last updated today
Built with Documentation.AI