Multi-Factor Authentication¶

Multi-factor authentication (MFA) adds a second verification step after your password — protecting your account even if your password is compromised.

b'nerd supports TOTP (Time-based One-Time Passwords, compatible with any standard authenticator app) and recovery codes as a backup method.

Enroll in MFA (TOTP)¶

1. Open the dashboard and go to Account → Security (/account/security).
2. In the Multi-Factor Authentication card, click Enable MFA.
3. The enrollment flow expands inline — no page navigation needed.

Step 1 — Scan the QR code¶

Scan the QR code with your authenticator app (Aegis, Authy, 1Password, Google Authenticator, and any other TOTP-compatible app).

If you cannot scan the QR code, click Can't scan? to reveal the manual Base32 secret key and enter it directly into your authenticator app.

Click Next → once your app has registered the account.

Step 2 — Confirm your first code¶

Enter the 6-digit code shown in your authenticator app, then click Verify & Enable.

• The code changes every 30 seconds — if it expires while you type, wait for the next one.
• If your code is rejected, check that your device clock is synchronized (see Troubleshooting).

Step 3 — Save your recovery codes¶

After the code is verified, 16 single-use recovery codes are displayed.

Each code can be used exactly once to sign in when your authenticator is unavailable. Once a code is used, it is permanently invalidated.

Click Done — I've saved my codes to finish enrollment.

Sign in with MFA¶

After entering your email and password on the login page, you are redirected to the two-factor challenge at /mfa/challenge.

TOTP challenge¶

Enter the current 6-digit code from your authenticator app and click Verify.

Recovery code challenge¶

If you cannot access your authenticator app, click Use a recovery code instead and enter one of your saved codes.

After a successful recovery code sign-in, the dashboard shows a banner reminding you to generate new codes. Recovery codes are single-use — once entered, each code is removed and cannot be reused.

Recovery codes¶

Remaining code count¶

The number of unused recovery codes is shown on Account → Security next to the Recovery codes section. The API also exposes this value at GET /accounts/me under mfa.recovery_codes_remaining.

Regenerate recovery codes¶

1. Go to Account → Security and expand the MFA manage section.
2. Click Regenerate codes.
3. Enter your current password to confirm.
4. Download or copy the new codes before clicking Done.

All previous codes are permanently invalidated the moment the new set is generated.

Disable MFA¶

1. Go to Account → Security and expand the MFA manage section.
2. Click Disable MFA (red outlined button at the bottom).
3. A confirmation dialog appears. Enter your current password and click Disable MFA to confirm.

Locked account¶

After too many incorrect sign-in attempts the platform locks your account.

Unlock via email¶

1. On the lock screen (/mfa/locked), click Send unlock email.
2. An unlock link is sent to your registered email address.
3. Click the link. You are taken to a confirmation page and can sign in again.

If the link has expired, click Send unlock email again to request a new one.

If you cannot receive the unlock email¶

Contact hello@bnerd.com and include your account email address.

Organization-enforced MFA¶

Organization admins can require all members of their organization to enroll in TOTP. Once enabled, any member who attempts an interactive browser login without MFA enrolled receives a 403 totp_setup_required response and is redirected to /mfa/setup to complete enrollment before the dashboard is accessible.

How it works¶

• The gate fires on interactive password-authenticated sessions only — static API tokens, CLI Bearer JWTs, and Terraform provider calls are unaffected.
• Platform (super) admins are subject to the existing admin hard-gate and are not additionally affected by the org-level toggle.
• The mfa_required field is returned on every GET /organizations/:id response so clients can reflect the current policy.

Enable org-enforced MFA¶

PATCH /organizations/{id}
Authorization: Bearer <org-admin-token>
Content-Type: application/json

{
  "organization": {
    "mfa_required": true
  }
}

Returns the updated Organization object with mfa_required: true. Only org-admin role members can set this field. Set "mfa_required": false to disable enforcement.

Member experience once enabled¶

Members who log in and have not yet enrolled in TOTP are blocked at the API layer (403 totp_setup_required) and the dashboard redirects them to /mfa/setup. That page runs the full enrollment flow (QR code → verify code → save recovery codes) in an isolated layout. After successful enrollment the member is forwarded to the dashboard normally.

API access and MFA¶

Static API tokens and CLI Bearer JWTs are not subject to the MFA gate. Only interactive browser logins require the second-factor challenge.

This means:

• Terraform provider API calls are unaffected by MFA enrollment.
• bnerd CLI token-based requests proceed without challenge.
• Dashboard browser sessions require MFA after enrollment.

See Authentication & Tokens for the full auth surface.

Troubleshooting¶

API reference¶

The MFA API is documented in the Interactive API Reference under the MFA tag.

Quick links:

See the MFA API reference page for request/response shapes and error codes.