Scoutinternal

Removing Users from Enterprise Accounts and Wallets

Removing Users from Enterprise Accounts and Wallets

Problem

Enterprise administrators frequently need to remove users (typically former employees) from wallets and enterprise accounts. This process is blocked when the user being removed is the sole admin on wallets, when the departing user cannot log in to accept their removal, when approval policies require more admins than are currently available, or when UI errors prevent the removal workflow from completing. The removal order matters: a user must be removed from all wallets before they can be removed from the enterprise.

Diagnostics

  • Confirm the removal order requirement: A user cannot be removed from an enterprise until they are removed from every wallet they belong to on that enterprise.
  • Identify wallet types the user is on: Check whether each wallet is a Custodial Wallet, Self-Managed Hot Wallet, or Go Account. BitGo Support's ability to intervene differs by type.
  • Check the user's permission level on each wallet: Determine whether the user is an Admin, Spender, or Viewer on each wallet. Use internal tooling or bga CLI to list wallet memberships.
  • Check whether the user is the sole admin on any wallet: If the user is the only admin, another admin must be added before removal can proceed.
  • Check the number-of-admin-approvals policy on the wallet: If the wallet requires two admin approvals and there are only two admins (one being the departing user), the approval policy may need to be reduced.
  • Check whether the departing user can still log in: If the user has left the company and cannot accept removal, determine whether the customer's IT team can regain access to the user's email to perform a password reset and 2FA reset.
  • Check the user's enterprise role: Determine if the user is an Owner, Member, or Primary Contact. Removing a Primary Contact or the Control Person requires additional verification (board resolution or signed letter).
  • Check for UI errors: If the customer reports "wallet not found" or other UI errors when attempting removal, reproduce the issue and check whether an engineering escalation is needed.
  • Check whether the enterprise has the userManagementServiceEnabled feature flag: Enterprises migrated to UMS may have different Admin Console workflows for role management.

Resolution

Scenario: remove-user-removal-users#custodial-wallet-removal

Trigger: The user needs to be removed from one or more Custodial Wallets and the customer requests BitGo Support assistance.

Signals: custodial wallet, remove user, add user, bulk removal, spender, admin, viewer, custodial

Steps:

  1. Confirm the wallet type is Custodial. BitGo Support can add and remove users at all permission levels (Admin, Spender, Viewer) on Custodial Wallets.
  2. If the user being removed holds Admin permissions, a video verification call is required. Direct the customer to schedule using: https://calendly.com/bitgo-client-delivery/videoid
  3. On the call, verify the requester's government-issued photo ID and confirm the Enterprise ID, Wallet IDs (confirming the first and last characters), user email to be removed, and user email to be added (if a replacement admin is needed).
  4. Perform the removal using bga CLI or internal tooling. If performing bulk removals across many wallets, compile and share a spreadsheet of wallets and changes with the customer for confirmation before executing.
  5. Once the user is removed from all wallets, proceed to remove them from the enterprise. Use bga ent removeuser or have the customer initiate from the UI.

Notes: For Viewers being removed from custodial wallets, video verification may not be required. Use judgment based on the sensitivity of the request. Bulk add/remove requests across many wallets are supported — request a list of wallet IDs and user emails from the customer.

"We are able to add and remove users from some wallets depending on the type of wallet: Custodial Wallets - We can Add and Remove users of all permissions levels. Non-Custodial Wallets - We can only Add and Remove users at Viewer level." "Removed > [EMAIL] Added > [EMAIL] as Spender ... bga ent removeuser [EMAIL] *** Removed [EMAIL] from CNK Fund III, L.P."

Scenario: remove-user-removal-users#hot-wallet-admin-removal

Trigger: The user is an Admin on a Self-Managed Hot Wallet and the customer wants BitGo to remove them.

Signals: hot wallet, self-managed, non-custodial, admin, cannot remove, accept removal

Steps:

  1. Inform the customer that BitGo Support can only add or remove users with Viewer permissions on Self-Managed Hot Wallets. Support cannot remove Admins or Spenders from these wallets.
  2. Advise the customer that another Admin on the wallet must request the removal via the UI, and the user being removed must log in and accept the removal.
  3. If the departing user is no longer with the company: a. The customer's IT team must regain access to the departing user's email account. b. The customer should reset the departing user's BitGo login password. c. An Enterprise Owner must schedule a video verification call to request a 2FA reset for the departing user's account. Direct them to: https://calendly.com/bitgo-client-delivery/videoid — the requester must present a government-issued photo ID. d. Once 2FA is reset, the customer re-establishes 2FA on their own device, logs in as the departing user, and accepts the pending removal requests.
  4. If the departing user is the sole admin on the hot wallet, advise the customer to first log in as that user (after regaining access) and add a new admin before initiating the removal.

Notes: If the wallet requires two admin approvals and only two admins exist (one departing), consider escalating to engineering to reduce the number of required admin approvals. This requires a video-verified request and a JIRA to the Custody Services team. Removing a user from the enterprise is not possible until they are removed from all wallets, including hot wallets.

"Your team will need to work with your IT team to gain access to Lydon's email address. From there, you will want to request a password reset for Lydon. Luke Thibodeau will need to schedule a time to meet with us over video to request reset of Lydon's 2FA for our platform. Once the 2FA is reset, your team can re-establish it on your own device and will be able to access the platform as Lydon." "For Self-Managed hot wallets, we can only affect users with 'Viewer' permission level. Your team would need to request her removal with the UI for each Self-Managed Hot Wallet and then login as Lindsay to accept these removals on her behalf." "For non-custodial wallets, we can only add/remove a user who is Spender and Viewer but not a user who is an Admin."

Scenario: remove-user-removal-users#go-account-wallet

Trigger: The user is on a Go Account wallet and needs to be removed or replaced.

Signals: Go Account, trading wallet, swap admin, go wallet

Steps:

  1. For Go Account wallets, BitGo Support can only swap out the current Admin with a new Admin. Direct removal without replacement is not supported.
  2. Confirm the replacement admin's email address with the customer.
  3. Schedule a video verification call if needed: https://calendly.com/bitgo-client-delivery/videoid
  4. Perform the admin swap using internal tooling.
  5. Advise the customer to complete any remaining removal steps (e.g., removing from enterprise) after the Go Account change is finalized.

Notes: The customer may need to handle additional removal actions on the Go Account themselves via the UI. In some cases, Support completed the removal from Go Accounts after the customer confirmed the swap was done on their end.

"For Go Account, we can only swap out the current Admin with a new Admin."

Scenario: remove-user-removal-users#approval-policy-blocking-removal

Trigger: The wallet's admin approval policy requires more approvals than available active admins, preventing user removal.

Signals: double admin approval, approval policy, pending approval, two admins, cannot approve, stuck in limbo

Steps:

  1. Confirm the wallet's current approval policy (number of admin approvals required) and the number of active admins remaining.
  2. Schedule a video verification call with the customer to authorize changing the number of required admin approvals: https://calendly.com/bitgo-client-delivery/videoid
  3. After video verification, create a JIRA to the Custody Services team requesting the admin approval count be reduced (e.g., from 2 to 1).
  4. Once engineering completes the change, instruct the customer to re-attempt the removal via the UI.
  5. After all removals are complete, the customer may want to restore the original approval policy.

Notes: This scenario is common when a company has had departures leaving only one or two active admins. The video verification and JIRA process may take a few business days.

"We may be able to change the number of Admin Approvals needed down to 1. ... David is looking to confirm we have his permission to change the number of Admin Approvals on these wallets so that only 1 admin approval is needed despite the number of admins on the wallets." "We need to wipe all of the policy in place on Non-custodial wallet ID: [WALLET_ID] (Mainly the 2 admin required to make a change setting) ... Once done, Hut 8 Will remove Shane from the wallet and finally remove him from the enterprise altogether."

Scenario: remove-user-removal-users#enterprise-owner-or-primary-contact-removal

Trigger: The user to be removed is an Enterprise Owner, Primary Contact, or Control Person.

Signals: owner, primary contact, control person, enterprise removal, board resolution, CP, BO

Steps:

  1. Determine whether the user is the Primary Contact and/or the Control Person (CP) on the application.
  2. If the Control Person is still with the company: a. Require a written verification (signed document from the CP on company letterhead) that explicitly states the individual(s) to be removed and the individual to be added as the new enterprise owner(s). Include the exact legal entity name and enterprise ID. b. Schedule a video verification with the original CP to confirm the details: https://calendly.com/bitgo-client-delivery/videoid
  3. If the Control Person is no longer with the company: a. Require a board resolution and a register of directors for the entity that specifies the individual(s) to be removed and the individual to be added. b. No video verification is required in this scenario.
  4. Submit the documentation to the Trust team for review and approval.
  5. Once approved, proceed with the user and primary contact changes.
  6. If multiple enterprise owners exist and they have equal rights, one owner cannot unilaterally remove another — the owner being removed must approve their own removal. If they are unavailable, follow the board resolution path.

Notes: Enterprise owners have equal rights. It is not possible for an Owner to remove another Owner without the Owner being removed approving the request. The only override path is the board resolution process through the Trust team.

"If the Control Person not with the company, then we need obtain a Board Resolution and Register of Directors: Obtain a board resolution and a register of directors for the entity that clearly specifies the individual(s) to be removed and the individual to be added. No video verification is required in this scenario." "To change Primary Contacts on the Enterprise, we will need a board resolution on company letterhead stating that Patrick is no longer with the org and stating who should be considered the single primary contact."

Scenario: remove-user-removal-users#user-sole-admin-on-wallet

Trigger: The user to be removed is the only admin on one or more wallets, so no other admin exists to initiate or approve the removal.

Signals: only admin, sole admin, add admin first, no other admin, wallet not found

Steps:

  1. Confirm via internal tooling that the user is the sole admin on the affected wallets.
  2. For Custodial Wallets: BitGo Support can add a new admin directly and then remove the departing user. Schedule a video verification call to authorize this.
  3. For Self-Managed Hot Wallets: The customer must log in as the departing user (regaining email access and resetting password/2FA if necessary) to add a new admin before removal can proceed.
  4. If the wallets are empty and no longer needed, suggest archiving or deleting the wallets instead of managing the user change. Archiving can be done via a video-verified request where Support archives the wallets on the backend.
  5. Once the user is no longer the sole admin (or the wallet is archived/deleted), proceed with removal from the enterprise.

Notes: If wallets show "wallet not found" errors in the UI, this may indicate a platform bug. Reproduce the error, escalate to engineering via JIRA, and inform the customer. In ticket #79524, engineering removed the user from inaccessible wallets directly on the backend.

"For an Admin who is being removed from wallets, the Admin being removed must login to accept the removal request. ... For him to be removed, another Admin would be needed on the wallet or the customer would need to schedule time with us to remove Baptiste and add a new Admin." "Unfortunately, we are unable to remove an Admin account from a Hot Wallet; this must be done by the Wallet Admin themselves. Alternatively, we suggest the following options: Archive these wallets if they are no longer needed. Deactivate the mentioned users. Remove the users from Enterprise ID ... as members."

Scenario: remove-user-removal-users#ui-error-or-bug-blocking-removal

Trigger: The customer encounters a UI error (e.g., "wallet not found", removal button not working, or users not appearing in the admin portal) when attempting to remove a user.

Signals: wallet not found, UI error, bug, cannot see wallet, error displayed, caching, remove button

Steps:

  1. First, ask the customer to clear their browser cache, update Chrome to the latest version, and retry.
  2. If the issue persists, ask the customer to capture browser console errors and network logs (Inspect > Console tab for red errors, Network tab for failed requests with headers and preview text).
  3. Attempt to reproduce the issue internally by spoofing the user's session or checking the wallets via internal tools.
  4. If reproducible, escalate to engineering via JIRA with the console/network logs, wallet IDs, and user details.
  5. Inform the customer that engineering is investigating and provide updates as they become available.
  6. In some cases, engineering resolves the issue by fixing backend data or removing the user/wallet directly.

Notes: In ticket #79524, wallets showed "wallet not found" errors due to a UI issue with AVAXC wallets; engineering removed the user from those wallets directly. In ticket #145983, a UI error prevented removal and engineering resolved it by fixing a backend bug. In ticket #266137, clearing browser cache resolved the issue of users not appearing in the admin portal list.

"Our engineering team has resolved the issue and you should see the remove button in the UI and should be able to remove the user from the wallet." "Our engineering removed Tariq from the wallets and now Ola is added as the only admin."

Scenario: remove-user-removal-users#departing-user-must-accept-removal

Trigger: The removal request is pending because the departing user must log in and accept it, but they have left the company.

Signals: pending approval, accept removal, departed employee, no longer with company, rogue actor, 2FA reset, password reset

Steps:

  1. Inform the customer that the platform requires the departing user to log in and accept their own removal from wallets and/or the enterprise.
  2. Advise the customer to work with their IT team to regain access to the departing user's email account.
  3. Once email access is regained, the customer should reset the departing user's BitGo password via the standard password reset flow.
  4. For the 2FA reset, an Enterprise Owner or authorized user must schedule a video verification call: https://calendly.com/bitgo-client-delivery/videoid. They must present a government-issued photo ID and reference the ticket number.
  5. After BitGo resets the 2FA, the customer sets up new 2FA on their own device, logs in as the departing user, and accepts all pending removal requests.
  6. Once the user is removed from all wallets, initiate their removal from the enterprise.

Notes: In cases where the customer cannot regain access to the departing user's email at all, the board resolution / Control Person verification path (see enterprise owner removal scenario) may be the only alternative. BitGo Support can also freeze the departing user's account as a precautionary measure while the removal process is underway.

"Now Joel has to login to his account and has to accept his removal. If he is no longer with the firm, then you need to regain his email access and need to reset his BitGo account password and need to login to his account. After the password reset, you also may need to reset his 2FA since it was previously setup on his phone. For 2FA reset any one of the account owners has to schedule a call with us and need to verify the request over the call." "As the user account was active, I did freeze the user account now. But please login to your BitGo account and switch to new UI to navigate to the account settings and remove the user from the BitGo Trust account."

Scenario: remove-user-removal-users#api-user-replacement

Trigger: The customer wants to remove or rename an API user (used for transaction signing) who is no longer with the company.

Signals: API user, access token, rename user, API, transaction signing

Steps:

  1. Advise the customer that it is not best practice to rename an existing user and change their email address, as this would require a password reset and would invalidate the user's KYC on file.
  2. Recommend the customer establish a new user for API purposes. This new user should create a new Access Token to authenticate API endpoints.
  3. Once the new API user and token are operational, the old API user can be removed following the standard user removal process.

Notes: This applies specifically to users whose accounts are used for API access tokens rather than interactive UI logins.

"We advise your team to establish a new user for API. This user would want to create a new Access Token used to authenticate the API endpoints being called. It is not in our best practices to rename an existing user and change email address to something else as this would require a password reset for their login which would cause further issues downstream. This would also invalidate that user's KYC on file."

Scenario: remove-user-removal-users#ums-admin-console-role-removal

Trigger: The enterprise uses the User Management Service (UMS) with the Admin Console, and the user's permissions are managed via roles rather than direct wallet shares.

Signals: Admin Console, UMS, roles, userManagementServiceEnabled, Edit Role, Revoke, custom role

Steps:

  1. Confirm the enterprise has the userManagementServiceEnabled feature flag.
  2. Instruct the customer (or an Organization Admin) to log in and navigate to Admin Console > Members.
  3. Search for the user to be removed. Click on the user to view their assigned roles.
  4. Under each role, click "View Role" then "Edit Role."
  5. To remove specific wallet permissions, under Enterprises > click "Select Wallets" and untick the wallets the user should no longer have access to.
  6. To fully remove the user, revoke all assigned roles.
  7. If the customer wants the user to retain only Viewer access, revoke all roles except "Wallet Viewer."
  8. Once all roles are revoked, the user can be removed from the enterprise via the standard removal flow (Admin Console > Roles > Org Admin Role > Members > trash icon).

Notes: In enterprises migrated to UMS, pre-existing wallet shares accepted after migration can cause synchronization issues between UMS and wallet permissions (WP). If a user has unexpected permissions after migration, escalate to engineering to reconcile the discrepancy.

"To finish removing Tom, please login to the Bitgo UI and select the Kbit Global Limited Enterprise. Choose the Profile Logo, then Admin Console. Once there, choose Roles. Choose the Org Admin Role > Members. Choose the trashcan icon next to Tom to remove them. This should not prompt/require an approval." "Upon further investigation, we found that the user had a pre-existing wallet share at the time the organization was migrated to UMS. After the migration, the user accepted the wallet share, which caused UMS and WP to become out of sync."

Related