Scoutinternal

Two-Factor Authentication (2FA) Issues: Login Failures, Invalid Codes, and Resets

Two-Factor Authentication (2FA) Issues: Login Failures, Invalid Codes, and Resets

Problem

Customers are unable to log in to their BitGo account because their Two-Factor Authentication (2FA) code is not working or is unavailable. Common scenarios include: the authenticator app (Google Authenticator, Microsoft Authenticator, or Authy) no longer generates a valid code for BitGo, the customer switched to a new mobile device and lost their 2FA configuration, or the 2FA code entered at login is rejected with an error such as "The authentication code is invalid." This affects access to the BitGo web application at https://app.bitgo.com/auth/log-in.

Diagnostics

  • Confirm which step is failing: Ask the customer whether they can successfully enter their email and password, and whether the failure occurs specifically at the 2FA prompt. Distinguish between a password issue and a 2FA issue.
  • Identify the authenticator app in use: Determine whether the customer is using Google Authenticator, Microsoft Authenticator, Authy, or another TOTP app. Check whether the customer has a BitGo entry visible in their authenticator app.
  • Check for device changes: Ask whether the customer has replaced their mobile phone since they last successfully logged in. Authenticator app TOTP seeds typically do not transfer automatically when switching devices.
  • Check the login method: Confirm whether the customer is logging in from a desktop/laptop browser (preferably Google Chrome) or from a mobile device browser. BitGo recommends the latest version of Google Chrome on a desktop or laptop.
  • Check for "Remember this device" behavior: If the customer reports that login bypasses the 2FA prompt entirely, they may have previously selected "Remember this device for 30 days." Verify the 2FA device setting in the account to confirm 2FA is still configured.
  • Look up the account's 2FA status: In the admin tools, check whether the customer's account has 2FA enabled and which 2FA method is configured.
  • Distinguish from wallet passphrase errors: If the customer sees "unable to decrypt keychain with the given wallet passphrase," the problem is a wallet password issue, not a 2FA issue. Direct them to the wallet-level "Forgot Wallet Password" flow instead.

Resolution

Scenario: authentication-authenticator-twostep-authy#new-device-lost-2fa

Trigger: The customer replaced their mobile phone and the authenticator app on the new device no longer has a BitGo entry or generates a valid code.

Signals: new phone, new device, authenticator empty, no code shows up, Google Authenticator no entry, lost 2FA, changed phone

Steps:

  1. Inform the customer that switching mobile devices typically causes the loss of TOTP authenticator configurations. A manual 2FA reset is required so they can reconfigure 2FA on their current device.
  2. Before resetting, verify the customer's ownership of the account. Request the following:
    • Date of BitGo email verification — instruct the customer to search their email inbox for "Your BitGo Email Verification" and provide the exact date.
    • Up to 3 transaction hashes (TXIDs) — either to or from their wallet. If they do not have these, advise them to contact the exchange from which they originally received funds and request the TXIDs.
    • Wallet balance — expressed in the crypto coin of the wallet.
    • First 8 characters and last 8 characters of the BitGo Public Key from their keycard.
    • Complete Wallet ID (if available).
  3. Cross-reference all provided information against BitGo's internal records. All items must match before proceeding.
  4. Once verified, perform the manual 2FA reset in the admin tools.
  5. Notify the customer that their 2FA has been reset and instruct them to log back in. They will be prompted to set up 2FA again during the next login.
  6. Advise the customer to download and securely store their recovery codes after re-enabling 2FA.

Notes: BitGo only offers email support — phone call requests should be politely declined. If the date of email verification provided by the customer does not match records, ask them to confirm that the email address they are contacting from is the same address associated with their BitGo account. The customer must provide accurate information; mismatches will block the reset to protect against unauthorized access.

"Before we can initiate the manual reset, we need to verify your ownership of the wallet. Therefore, we will require the following: Date of BitGo email verification (search for 'Your BitGo Email Verification' in inbox), 3 transaction hashes either to or from your wallet... Wallet balance" (ticket #76337)

"Could you also provide us the complete Wallet ID and the First 8 characters and the Last 8 Characters of the BitGo Public Key from your keycard." (ticket #76337)

"We completed the process of resetting your Two-Factor Authentication. Please log back into your account, and follow the instructions to set up your Two-Factor Authentication again." (ticket #76337)

Scenario: authentication-authenticator-twostep-authy#invalid-code-same-device

Trigger: The customer still has their original device and sees a BitGo entry in their authenticator app, but the generated code is rejected with an error such as "The authentication code is invalid."

Signals: invalid code, authentication code invalid, code not working, invalid token, Authy code not working, TOTP rejected

Steps:

  1. Ask the customer for a full-window screenshot of the error they receive.
  2. Verify that the customer's device clock is accurate. TOTP codes are time-sensitive; a device clock that is out of sync (even by 30–60 seconds) will generate invalid codes. Advise the customer to enable automatic time synchronization on their phone.
  3. Confirm the customer is entering the code promptly — codes typically rotate every 30–60 seconds.
  4. Recommend the customer use the latest version of Google Chrome on a desktop or laptop computer.
  5. If the code continues to fail after time-sync verification, proceed with a manual 2FA reset using the same ownership verification process as the "new device" scenario above (email verification date, up to 3 TXIDs, wallet balance, first 8 / last 8 characters of the BitGo Public Key, Wallet ID).
  6. After reset, advise the customer to log in and reconfigure 2FA, then download recovery codes.

Notes: After a 2FA reset, if the customer experiences a blurred screen or UI issue when trying to create an access token or perform other actions, advise them to retry from Chrome browser.

"If your 2FA is not working for you, all we can do is reset it." (ticket #204800)

"Thank you for the reply. Please retry from Chrome browser." (ticket #204800)

Scenario: authentication-authenticator-twostep-authy#2fa-setup-error

Trigger: The customer is a new or existing user attempting to set up 2FA for the first time (or reconfigure it after a reset) and encounters an error during the authenticator setup flow, potentially including errors from Microsoft Authenticator.

Signals: authenticator setup error, cannot proceed with authenticator, error during setup, bg-ui error, Microsoft Authenticator error, ErrorID

Steps:

  1. Ask the customer for a full-window screenshot of the error, including any ErrorID displayed.
  2. Instruct the customer to set up 2FA by logging in from a desktop or laptop computer (using the latest version of Google Chrome) while using the authenticator app on their mobile device to scan the QR code. Do not attempt setup from a mobile browser.
  3. Confirm the customer is using a supported authenticator app (Google Authenticator or Microsoft Authenticator).
  4. If the error persists, ask the customer to try from a different device and/or network.
  5. If the issue remains unresolved after the above steps, escalate to engineering with the ErrorID and screenshots.

Notes: Some customers attempt to set up 2FA entirely from a mobile device browser, which can cause errors. The recommended flow is desktop browser + mobile authenticator app.

"Setup your 2FA by attempting to login from a desktop or laptop computer with the authenticator on your mobile device." (ticket #280225)

Scenario: authentication-authenticator-twostep-authy#2fa-not-prompted-remember-device

Trigger: The customer reports that after entering email and password, they are logged in immediately without being prompted for a 2FA code, and they are concerned about security.

Signals: no 2FA prompt, logged in immediately, remember this device, security concern, balance visible without 2FA

Steps:

  1. Check the customer's account to confirm that 2FA is still configured (e.g., Google Authenticator).
  2. Explain to the customer that they may have previously selected "Remember this device for 30 days" during a prior login, which suppresses the 2FA prompt on that device and browser for the duration of the 30-day window.
  3. Advise the customer to try logging in from a different device or browser where they have not previously chosen to remember the device — they should be prompted for 2FA there.
  4. If the customer wants to ensure 2FA is always required, advise them to clear their browser cookies for the BitGo domain or use a private/incognito browser session.

Notes: This is expected behavior, not a security vulnerability. The "Remember this device for 30 days" option is a standard UX convenience feature.

"Please try logging in from the device where it is set up. It's possible that you may have selected 'Remember this device for 30 days' during a previous login, which is why you are not being prompted for the 2FA code." (ticket #251281)

Scenario: authentication-authenticator-twostep-authy#wallet-passphrase-not-2fa

Trigger: The customer reports an "authentication" issue but the actual error is "unable to decrypt keychain with the given wallet passphrase," which is a wallet password problem, not a 2FA problem.

Signals: unable to decrypt keychain, wallet passphrase, wallet password, Forgot Wallet Password

Steps:

  1. Clarify to the customer that this is a wallet password issue, not a 2FA issue. The account login and 2FA are working correctly.
  2. Instruct the customer to navigate to the Settings tab of their specific wallet (not Account Settings).
  3. Within the wallet Settings tab, locate the "Forgot Wallet Password" hyperlink.
  4. Advise the customer to follow that flow to resync their wallet password with their login password.
  5. Recommend the customer use the latest version of Google Chrome on a desktop or laptop. If the customer is on a mobile browser, ask them to switch to desktop.
  6. If the customer cannot find the option, advise them to switch to classic view first, then retry.

Notes: The "Forgot Wallet Password" link is on the individual wallet's Settings tab, not on the Account Password page. Customers frequently confuse the two. Advise switching to "classic view" if the option is not visible.

"Please navigate to the Settings tab of your Go Account wallet. There you will find the 'Forgot Wallet Password' hyperlink. Choosing this will begin the flow to resync your wallet password with your login password." (ticket #324052)

"Could you please switch to classic view first and then follow the steps suggested (via Google Chrome Browser on Laptop or Desktop)." (ticket #324052)

Related