Two-Factor Authentication (Staff)

Two-Factor Authentication (Staff)#

Staff accounts in Commerce support TOTP-based two-factor authentication (2FA). 2FA is opt-in and self-managed — each staff member enables it on their own profile. Admins cannot force-enable it for others, but requiring 2FA org-wide is on the roadmap.

Setting Up 2FA#

1. Log in to the admin panel.
2. Go to your profile: click your name in the top-right → Profile, or navigate directly to /admin/profile.
3. Scroll to the Two-Factor Authentication section.
4. Click Enable Two-Factor Authentication.
5. A QR code is displayed. Scan it with your authenticator app:
   • Google Authenticator
   • Authy
   • 1Password
   • Bitwarden Authenticator
   • Any TOTP-compatible app
6. Enter the 6-digit code currently shown in your app to confirm setup.
7. Click Confirm.

Backup Codes#

Immediately after confirming, Commerce displays 8 one-time backup codes.

[!WARNING] Download or copy your backup codes before leaving this page. They are shown only once. If you lose access to your authenticator and have no backup codes, you will need another super_admin to disable your 2FA from the database directly.

Store backup codes in a password manager, not in your email inbox.

Logging In with 2FA Active#

1. Visit /admin/login and enter your email and password as usual.
2. Commerce redirects you to /admin/two-factor.
3. Enter the 6-digit TOTP code from your authenticator app.
4. Click Verify — you are logged in.

Using a Backup Code#

On the /admin/two-factor screen, click Use a backup code and enter one of your 8 codes. Each backup code is single-use — it is invalidated immediately after use. You have 7 remaining after the first use.

[!TIP] If you are running low on backup codes, disable and re-enable 2FA to generate a fresh set of 8.

Disabling 2FA#

1. Go to your profile at /admin/profile.
2. Click Disable Two-Factor Authentication.
3. Enter your current password to confirm.
4. Click Disable.

2FA is now off. Your TOTP secret and remaining backup codes are deleted.

[!IMPORTANT] An admin cannot disable 2FA for another staff member through the UI. 2FA is self-service only. If a staff member is locked out, a super_admin can reset their 2FA from the CLI:

php artisan commerce:staff:disable-2fa staff@example.com

Security Notes#

• TOTP codes are time-based (30-second window) — ensure your authenticator device's clock is accurate.
• Commerce accepts one code from the ±1 window (90-second tolerance) to account for minor clock drift.
• Backup codes are stored as bcrypt hashes in the database — they cannot be recovered, only regenerated.
• Successful and failed 2FA attempts are logged in Admin → Activity Log.