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 to your email/password login using a code from an authenticator app. You set it up from Profile and can also generate backup codes there in case you lose access to your authenticator.

If you sign in via SSO (OIDC), MFA is handled by your identity provider — SlugBase does not add an extra code step after SSO login. See MFA and SSO (OIDC) below.

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.

MFA and SSO (OIDC)

OIDC-only accounts (no local password): SlugBase does not show a second TOTP step after SSO. Your organization’s IdP is expected to enforce MFA according to its own policy.
Accounts that also have a password: Email/password sign-in still uses SlugBase MFA when it is enabled; OIDC sign-in does not add a second SlugBase TOTP step (the IdP handles strong authentication).

The Profile screen explains this when you sign in with SSO only.

Sign in with email and password (or OIDC if you use SSO—see above; no extra SlugBase TOTP step after OIDC).
If you used email/password and MFA is enabled on your account, you are prompted for a 6-digit code or you land on the MFA challenge screen.
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 (created under Profile → Developer / API Access) do not require an MFA code — the token itself is the authentication. This is intentional for scripts and tools that can't complete interactive prompts. Keep your tokens secret and revoke them if compromised.

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.

Profile and preferences

Where account settings and MFA controls live.

API tokens

Bearer tokens for the REST API; no MFA step on each request.

Was this page helpful?

Last updated 2 weeks ago

Built with Documentation.AI