Scoutinternal

Troubleshooting Errors When Adding Users to BitGo Wallets

Troubleshooting Errors When Adding Users to BitGo Wallets

Problem

Customers frequently encounter errors or unexpected behavior when attempting to add users (as Admin, Spender, or Viewer) to wallets via the BitGo UI or API. Common symptoms include "key not found" errors, "ApiResponseError" messages, users not seeing wallets after being invited, newly created wallets having no admin assigned, and the inability to change a user's role. These issues span all coin types and affect both self-managed (hot) and custodial (cold) wallets.

Diagnostics

  • Identify the wallet type: Determine whether the wallet is custodial (cold) or self-managed (hot). BitGo Support can add/remove users on custodial wallets but cannot add or remove users on hot wallets due to key encryption limitations.
  • Check the invited user's account status: In the admin tools, verify whether the user being added has: (1) logged in to BitGo at least once, (2) configured 2FA, and (3) completed KYC/sanctions screening. A missing keychain (sharing key) is the most common cause of "key not found" errors.
  • Check the inviting user's wallet permissions: Confirm the person attempting the invite has Admin permission on the specific wallet. A user with only Spender or Viewer permission cannot add other users. Look for the error "spend permission required for sharing with spend permission" as a signal of insufficient permissions.
  • Check Enterprise settings: Verify whether Users can view all wallets is enabled on the enterprise. When this flag is on, the Viewer role option is hidden from the wallet invite UI because all enterprise members already have implicit view access. This also means the implicit view is UI-only and does not grant API access to wallet data.
  • Check for the new User Management System (Admin Console): Determine if the enterprise has the Admin Console / UMS enabled. If so, wallet permissions are managed through Roles in the Admin Console (accessed via Profile Logo > Admin Console), not from the wallet's Users tab directly. Wallets created under UMS may not automatically assign admin to the creator if no role is configured for it.
  • Check pending approvals: If the enterprise has an approval policy requiring multiple admins, verify that all required approvals have been actioned. If the only other admin is a departed employee, special recovery steps (2FA reset via video call) may be needed.
  • Check the Bell Icon / Activity page: For self-managed hot wallets under UMS, verify whether the admin who created the wallet or who already holds the key has completed the key sharing request visible under the Activity / Notifications section (Bell Icon at top of screen). Until the key is shared and accepted, users are added as Viewers only.
  • Gather information for escalation: Wallet ID, Enterprise ID, email addresses of the inviting user and the invited user, the exact error message and ErrorID, and the intended role (Admin/Spender/Viewer).

Resolution

Scenario: user-admin-add-wallets#invited-user-account-incomplete

Trigger: The user being added to the wallet has not completed their BitGo account setup (first login, 2FA configuration, and/or KYC verification).

Signals: key not found, ApiResponseError, user.sharingkey 404 error, keychain missing, account not activated, KYC pending

Steps:

  1. Confirm in admin tools that the invited user's account is missing a keychain or has not completed KYC/2FA setup.
  2. Advise the customer to have the invited user log in to BitGo at https://app.bitgo.com/auth/log-in, configure 2FA, and complete KYC/sanctions screening.
  3. If KYC appears stuck or pending, escalate to the compliance team to check for issues or to provide a new Persona verification link.
  4. Once the invited user has completed setup and their keychain is created, instruct the admin to retry the wallet invitation.

Notes: This is the single most common cause of "key not found" errors. The error occurs because BitGo encrypts key shares against the invited user's credentials, which do not exist until first successful login and setup. Adding multiple users at once is an "all or nothing" action — if even one user has not completed setup, the entire batch invite will fail. In that case, advise inviting users one at a time.

"[EMAIL] is missing the keychain that gets created once the user logs in successfully for the first time and completes sanction screening." "one of the people I invited didn't activate their BitGo account yet. Was just alarmed at the error message saying that a key was not found." "I am showing that Andrea has not completed the setup of their account. Can you please have them login, configure 2FA, and submit KYC."

Scenario: user-admin-add-wallets#old-ui-keychain-bug

Trigger: The invited user completed account setup via the new UI but their keychain was not properly created; switching to the old/classic UI and logging in resolved the issue.

Signals: key not found, new UI, classic view, bug, keychain not created

Steps:

  1. If the invited user has completed setup via the new UI but the "key not found" error persists, ask them to log out and switch back to the old/classic UI view.
  2. Have the user log in via the classic UI to trigger keychain creation.
  3. Retry the wallet invitation after the user successfully logs in via classic view.
  4. If the issue persists, escalate to engineering as a potential platform bug.

Notes: This was identified as a bug by engineering in at least one case. The root cause was confirmed fixed, but it may recur if UI changes are deployed.

"We got his profile to work by switching back to the old UI and having him log in. Seemed to fix the issue on Friday. He had definitly logged in and registered via the new UI but needed to log back to the old one. Guess there is a bug somewhere."

Scenario: user-admin-add-wallets#wrong-enterprise-selected

Trigger: The invited user has logged in and accepted the invite but cannot see any wallets or pending invitations.

Signals: no wallets visible, no pending invitation, wrong enterprise, dropdown

Steps:

  1. Ask the invited user to check the enterprise dropdown menu in the upper left corner of the screen.
  2. Ensure the correct enterprise is selected — the user may be viewing a different enterprise or their personal account.
  3. Once the correct enterprise is selected, wallets and pending invitations should become visible.

Notes: Users who belong to multiple enterprises commonly land on the wrong one after login.

"Please make sure the user is in the correct Enterprise. Enterprise can be changed by choosing the dropdown menu in the upper left corner of the screen."

Scenario: user-admin-add-wallets#insufficient-wallet-permissions

Trigger: The user attempting to add another user receives an error indicating they lack the required permission, such as "spend permission required for sharing with spend permission."

Signals: spend permission required, ApiResponseError, spender cannot add spender, insufficient permissions, admin required

Steps:

  1. Verify the inviting user's permission on the specific wallet. Only users with Admin permission on the wallet can invite other users.
  2. If the inviting user is only a Spender or Viewer, they must ask an existing wallet Admin to perform the invite or to elevate their permissions.
  3. Under the new Admin Console / UMS, note that wallet-level Admin permission and Enterprise-level Org Admin are separate. Having an Org Admin role does not automatically grant wallet-level Admin. Check the user's custom role or default role assignments.
  4. If permission levels need to be adjusted, navigate to Profile Logo > Admin Console > Roles, select or create the appropriate role, and assign the correct wallet permissions.

Notes: With the introduction of the Admin Console, Admin permission on a wallet no longer automatically includes Spender or Trader permissions — these are now segmented.

"The error message indicates that the person trying to add the spender does not have the necessary permissions. Only users with the Owner or Admin role can add a new spender—a spender cannot add another spender." "ApiResponseError spend permission required for sharing with spend permission > indicates that the account you share with the wallet needs to have Spender Permission"

Scenario: user-admin-add-wallets#view-all-wallets-flag-blocks-viewer-add

Trigger: The admin cannot see a "Viewer" option when adding a user, or the API user cannot access wallet data despite being on the enterprise.

Signals: no viewer role, Users can view all wallets, API access denied, viewer not available, limited read-only UI-only view

Steps:

  1. Check the enterprise settings for the Users can view all wallets flag.
  2. Explain to the customer that when this flag is enabled, all enterprise members already have implicit view-only access via the UI, so the Viewer option is hidden from the wallet invite flow.
  3. Important: This implicit view is UI-only and does not grant API-level access to wallet data. For API access, the user must be explicitly added with a permission (Admin or Spender) on the wallet.
  4. If the customer needs to add explicit Viewer permissions (e.g., for API access), the Users can view all wallets flag must be temporarily disabled on the enterprise so the Viewer permission option becomes available when adding users.
  5. After adding the explicit Viewer permission, the flag can be re-enabled if desired.

Notes: This is a common source of confusion when customers create API tokens for users who appear to have access in the UI but receive empty results from the API.

"This flag provides a limited read-only, UI-only view for wallets. For a user to be added with true view permissions, this feature needs to be briefly disabled so the permission set can be chosen when adding." "If the 'Users can view all wallets' is enabled on the enterprise, you cannot add viewers to the wallet since they have this permission already."

Scenario: user-admin-add-wallets#admin-console-ums-role-misconfiguration

Trigger: Wallets created under the new Admin Console / User Management System have no admin assigned, or the wallet creator is assigned only as Viewer on their own wallet.

Signals: no admin on wallet, viewer instead of admin, Admin Console, User Management System, Wallet Admin Role, Wallet Spender Role, custom roles, new wallets created without users

Steps:

  1. Confirm the enterprise has the new User Management System / Admin Console enabled.
  2. Instruct the Enterprise Owner to access the Admin Console via Profile Logo > Admin Console.
  3. Navigate to the Roles tab. Check whether the Wallet Admin Role and Wallet Spender Role have members assigned. If not, invite the appropriate members to these roles.
  4. For automatic assignment on wallet creation, check whether the role is configured to automatically add members to newly created wallets. There is an option within the console to enable this.
  5. For finer-grained control, recommend creating custom roles for individual users. Custom roles allow assigning specific permission levels (Admin, Spender, Viewer, Trader) on specific wallets.
  6. To change a user's permissions on a wallet under UMS, the user must be removed and re-added with the new permissions — direct permission modification is not supported.
  7. Provide the customer with the Admin Console documentation:
    • https://landing.bitgo.com/rs/552-OGK-141/images/AdminConsoleUserGuide-July25.pdf?version=1
    • https://landing.bitgo.com/rs/552-OGK-141/images/AdminConsoleMigration.pdf?version=0
    • https://landing.bitgo.com/rs/552-OGK-141/images/RolesandPermissionsMatrix-July25.pdf?version=0

Notes: Under UMS, Enterprise-level roles (Org Admin, Enterprise Admin) are distinct from wallet-level roles (Wallet Admin, Wallet Spender). Being an "Organization Admin" does not automatically grant wallet Admin. The wallet Users tab may be greyed out; all management flows through the Admin Console.

"I am showing the Enterprise for this wallet has the new User Management System enabled which changes the way permissions are setup for users. For wallet permissions, Roles are setup which can provide various levels of permissions to different subsets of wallets." "There is an option with the console to automatically add a user to a wallet upon creation. This must be checked for this to occur." "you currently have view-only access to the wallet, not admin access... to update your access, you need to be removed and re-added with the new permissions—your current access level cannot be modified directly."

Scenario: user-admin-add-wallets#key-sharing-not-completed

Trigger: A user has been assigned a Spender or Admin role on a self-managed hot wallet but still only has Viewer access and cannot transact.

Signals: withdrawal not enabled, viewer only, key sharing, Bell Icon, Activity page, notifications, pending actions, accept wallet share

Steps:

  1. Ask the existing key holder (typically the wallet creator or an existing admin with spend access) to log in and check the Activity page or the Bell Icon (notifications) at the top of the screen.
  2. The key holder should find a key sharing request and share the wallet keys with the newly added user.
  3. The newly added user must then log in and accept the wallet share from their own Activity / Notifications section.
  4. Once the key share is accepted, the user's permission should update from Viewer to the assigned role (Spender/Admin).

Notes: This applies specifically to self-managed (hot) wallets where private key encryption is user-password-based. Until the key is shared and accepted, users are effectively Viewers regardless of their assigned role.

"Please ask William to log in to the account and check the notifications section. There, he should find the key sharing request, which needs to be shared with [the invited user]. Once that is done, the finance email should gain access." "Has this user accepted the wallet shared keys for these wallets? If they login and choose the Bell Icon at the top of the screen, are there any pending actions for them to address?"

Scenario: user-admin-add-wallets#changing-user-role-requires-remove-readd

Trigger: Customer wants to change a user's role on a wallet (e.g., from Spender to Admin) but finds no option to edit the role directly.

Signals: change role, spender to admin, upgrade permission, remove and readd

Steps:

  1. Explain that BitGo does not support direct role modification on a wallet. The user must be removed from the wallet and then re-added with the desired new role.
  2. Before removing, advise the customer to ensure there are no pending withdrawals or approvals initiated by the user being removed.
  3. Navigate to Wallet > Users, remove the user.
  4. Once removal is complete (and any required approvals are actioned), re-add the user with the new role.

Notes: Under the Admin Console, role changes also follow this pattern. Removal may trigger approval workflows if the enterprise has approval policies configured.

"Can you navigate to Wallet--> Users---> Then remove the user as a spender... Yes, to be safe, we would suggest not to have any pending withdrawal initiated by the user before removing him."

Scenario: user-admin-add-wallets#departed-admin-blocks-approval

Trigger: An admin who is required to approve the addition of a new user has left the organization and cannot log in, blocking the approval workflow.

Signals: retired user, departed admin, approval required, cannot approve, quorum lost, 2FA reset

Steps:

  1. Determine if the wallet is custodial or self-managed (hot).
  2. For custodial wallets: BitGo Support can add/remove users. A video verification call is required. Direct the customer to schedule via https://calendly.com/bitgo-client-delivery/videoid. On the call, the customer must confirm the first 4 and last 4 characters of the wallet ID and enterprise ID. A video-verified user on the enterprise must join or authorize the call.
  3. For hot wallets: BitGo cannot add or remove users due to key encryption limitations. The customer's IT team must regain access to the departed user's email. Once email access is restored, BitGo can assist with a 2FA reset (requires a video verification call with an already-verified user on the enterprise). After regaining access, the departed user's account can approve the pending addition, and then the departed user can be removed.
  4. As an alternative for hot wallets, if the wallets are no longer needed, they can be archived to prevent the departed user from taking action, though this does not remove them from the platform.

Notes: BitGo cannot remove users from hot wallets or reset wallet passwords. Archiving a wallet prevents actions on it but does not revoke the user's login access to the platform.

"This wallet is a hotwallet so unfortunately we are not able to assist as we are not able to add or remove admins due to key encryption limitation. The only way to move forward, is to work with your IT team to regain access to the email of the user..." "We will need either of you on the call to authorize the additions of your users to these wallets. On the call, we will ask you to confirm the first 4 and last 4 of these wallets IDs."

Scenario: user-admin-add-wallets#bulk-user-add-to-custodial-wallets

Trigger: Customer needs to add one or more users to a large number of custodial wallets and cannot do so efficiently through the UI.

Signals: bulk add, multiple wallets, custodial, add user to all wallets, large number of wallets

Steps:

  1. Confirm all wallets are custodial (not self-managed/hot). BitGo Support can only perform bulk additions on custodial wallets.
  2. Ask the customer to provide: (a) the email addresses of users to be added, (b) the desired role for each user, (c) the full list of wallet IDs, and (d) the enterprise ID.
  3. Schedule a video verification call via https://calendly.com/bitgo-client-delivery/videoid. An already video-verified user on the enterprise must attend or authorize the request.
  4. On the call, the customer confirms the request (e.g., "I confirm the addition of X user as [role] to the list of wallets provided").
  5. BitGo Support performs the bulk addition and follows up with confirmation.

Notes: Enterprise owners can also use the API to add users to wallets. The API endpoint is documented at https://developers.bitgo.com/guides/wallets/users/add. For the UI path: Assets > Wallet > Users > + Add User.

"Please use the following link to schedule a time to meet with us and verify the request: https://calendly.com/bitgo-client-delivery/videoid What role on the wallets will this user be? Admin, Spender, or Viewer? Can you confirm for us all wallets on this list are Custodial and not Self-Managed?"

Scenario: user-admin-add-wallets#enterprise-vs-wallet-permissions-confusion

Trigger: Customer added a user to the enterprise (Users & Invites) but the user cannot see or interact with specific wallets because they were not added at the wallet level.

Signals: added to enterprise but no wallet access, cannot view wallet, enterprise user vs wallet user, Users & Invites

Steps:

  1. Explain the distinction between enterprise-level and wallet-level permissions:
    • Enterprise roles: Owner or User. Owners can invite people to the enterprise and create wallets. Users have basic enterprise membership.
    • Wallet roles: Admin, Spender, Viewer, Trader. These must be assigned separately per wallet.
  2. Instruct the admin to navigate to each wallet where access is needed: Assets > select Wallet > Users tab (or Admin Console under UMS) > + Add User.
  3. Select the user from the dropdown, choose the desired wallet role, and complete the invitation.
  4. The invited user will receive a notification and must accept the wallet invitation.

Notes: Only Enterprise Owners can create wallets via the UI. Other users can create wallets via the API if they have an API Access Token created by an Owner.

"You will want to login to our platform, choose the wallet Tiah should be able to view, choose the Wallet Settings tab, and then scroll down to Users. You can invite them there as a 'Viewer'." "For Enterprises, users have one of two roles, Owner or User. Owners can invite people to the Enterprise and can create new wallets... For Wallets, users on wallets can have one of the following permissions, Admin, Spender, Viewer, and/or Trader. Only a wallet admin can invite people to have permissions on a wallet."

Scenario: user-admin-add-wallets#wallet-list-ui-pagination-bug

Trigger: When viewing a user's wallet list under Enterprise Settings > Users & Invites, the list is truncated with no pagination or infinite scroll, making it impossible to see all wallets for users on more than ~100 wallets.

Signals: UI bug, wallet list truncated, pagination, infinite scroll, more than 100 wallets

Steps:

  1. Acknowledge the issue as a known UI bug.
  2. Escalate to the Engineering team for review if the customer reports it is still occurring.
  3. In a previous instance, engineering deployed a fix to enable infinite scrolling on the wallet list.

Notes: This was reported and fixed previously, but may recur with UI updates.

"Yes, this looks to be a UI bug which we can reproduce. We have referred this to our Engineering Team for review... We have fixed this and you should now be able to scroll indefinitely on the wallet list."

Related