Everyone

Two-Factor Authentication (Client)

How clients enable TOTP-based two-factor authentication and use backup codes.

Last updated 1776211200
  • Login Flow with 2FA Enabled
  • Disabling 2FA
  • Lost Authenticator and All Backup Codes
  • Compatibility
  • Related Articles

    • Overview

    Commerce supports time-based one-time password (TOTP) two-factor authentication as defined in RFC 6238. 2FA is implemented in pure PHP with no third-party service dependency. When enabled, a six-digit code from an authenticator app is required in addition to your password at each login.

    Enabling 2FA

    1. Go to Client → Profile → Security tab.
    2. Click Enable Two-Factor Authentication.
    3. A QR code is displayed along with a manual entry key (for authenticator apps that do not support scanning).
    4. Open your authenticator app (Google Authenticator, Authy, Bitwarden, 1Password, or any RFC 6238-compatible app).
    5. Scan the QR code or manually enter the key.
    6. Enter the 6-digit code currently shown in your app to confirm pairing.
    7. Click Confirm & Enable.

    If the code is correct, 2FA is enabled immediately and your backup codes are displayed.

    Backup Codes

    When you enable 2FA, 8 single-use backup codes are generated and shown once. Each code can be used in place of a TOTP code at the login challenge step.

    [!IMPORTANT] Save your backup codes immediately. Store them in a password manager, print them, or write them down and keep them somewhere secure. They will not be shown again after you leave this page.

    Using a Backup Code

    At the 2FA challenge step during login, click Use a backup code instead of entering your TOTP code. Enter one of your saved backup codes. That code is consumed and cannot be used again.

    Regenerating Backup Codes

    If you are running low on backup codes (or suspect they were compromised):

    1. Go to Client → Profile → Security.
    2. Click Regenerate Backup Codes.
    3. Enter your current password to confirm.
    4. The new set of 8 codes is displayed. Save them immediately. All previous backup codes are invalidated.

    Login Flow with 2FA Enabled

    1. Enter your email and password at /client/login as normal.
    2. If credentials are correct and 2FA is enabled, you are redirected to the 2FA challenge page instead of the dashboard.
    3. Open your authenticator app and enter the current 6-digit code.
    4. Click Verify. If correct, you are logged in and redirected to the client dashboard.

    The TOTP code changes every 30 seconds. Commerce accepts codes up to 30 seconds before and after the current window to account for clock drift.

    Disabling 2FA

    1. Go to Client → Profile → Security.
    2. Click Disable Two-Factor Authentication.
    3. Enter your current password to confirm.
    4. 2FA is disabled and removed from your account.

    [!TIP] You do not need a TOTP code to disable 2FA if you are already logged in. Your password is sufficient as a second confirmation.

    Lost Authenticator and All Backup Codes

    If a client has lost access to their authenticator app and has no remaining backup codes, they cannot log in through the normal portal. To regain access:

    1. Contact your hosting provider's support team.
    2. A staff member can reset 2FA via the database (direct UPDATE on the client_2fa table to clear the secret and backup codes).

    [!IMPORTANT] Staff cannot view or bypass a client's 2FA code from the admin panel UI — there is no admin button for this. A database-level reset is required, which is why identity verification by the support team is important before performing this action.

    Compatibility

    Any RFC 6238-compliant authenticator app works with Commerce 2FA. Tested apps include:

    • Google Authenticator (iOS/Android)
    • Authy (iOS/Android/Desktop)
    • Bitwarden Authenticator
    • 1Password
    • Microsoft Authenticator

    Related Articles

    Previous
    ← Account Profile & Password
    Next
    API Tokens →