Ctrl+K

Set Up Organization

Overview

An organization is a grouping mechanism that's a level above an enterprise. Organizations can contain many enterprises, but enterprises can belong to only 1 organization. Within your organization, you can set up a child enterprise for each of your users, enabling them to independently take certain actions such as initiating trades and withdrawals. However, you can also collectively manage certain things for child enterprises, including segregating assets across Go Accounts.

Organizations require organization admins, who are people you select from among your enterprise admins. Organization admins can access child enterprise details, such as balances and addresses. Organization admins are also responsible for managing organization-wide policies that affect all child enterprises. Unlike the service user, organization admins can't initiate transactions, such as trades and withdrawals.

Note: Organization admins and the service user are two separate roles. Although it's likely that the organization admin has access to the service user, these are still distinct roles in BitGo-as-a-Service.

Similar to how your enterprise has an enterprise name and enterprise ID, your organization has an organization name and organization ID. The enterprise name and the organization name are the same. However, enterprise IDs and organization IDs always differ.

Prerequisites

Get Started

1. Create Short-Lived Access Token

To programmatically add users to an enterprise, you must create a short-lived (1 hour) access token to authenticate your requests to the BitGo API. You can bypass this step (and the next step) by using the web UI to add users to your enterprise.

Endpoint: Login

  • cURL
1
2
3
4
5
6
7
8
9
10
11
export ACCESS_TOKEN="YOU_ACCESS_TOKEN"

curl -X POST \
  "https://app.bitgo-test.com/api/v2/user/login" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "email": "<YOUR_LOGIN_EMAIL>",
    "otp": "000000", # testnet otp is always 000000
    "password": "<YOUR_LOGIN_PASSWORD>" # BitGo recommends passing you hashed password that the SDK provides from the preprocessAuthenticationParams function
}'

Step Result

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
{
  "token_type": "bearer",
  "access_token": "c9e4574dea9c706377907177d2861bf17e65476587cda449c08d81024aad8f5f",
  "expires_in": 86400,
  "expires_at": 1710016687,
  "scope": [
    "user_manage",
    "openid",
    "openid_enterprises",
    "profile",
    "wallet_create",
    "wallet_freeze_all",
    "wallet_manage_all",
    "wallet_approve_all",
    "wallet_spend_all",
    "wallet_edit_all",
    "wallet_view_all",
    "settlement_network_read",
    "settlement_network_write",
    "trade_view",
    "trade_trade",
    "portfolio_view",
    "pending_approval_update",
    "metamask_institutional",
    "crypto_compare",
    "third_party_user_lookup",
    "enterprise_view_all",
    "enterprise_manage_all"
  ],
  "user": {
    "id": "62ab90e06dfda30007974f0a52a12995",
    "username": "nakamoto@bitcoin.com",
    "enterprises": [
      {
        "id": "61fab88a336c18000813831c85a3f2fe",
        "permissions": ["admin"],
        "beneficialOwner": false
      },
      {
        "id": "62c5ae8174ac860007aff138a2d74df7",
        "permissions": ["admin"],
        "beneficialOwner": false
      },
      {
        "id": "640971cfba5a34e391cd52daaaffd4c6",
        "permissions": ["admin"],
        "beneficialOwner": false
      },
      {
        "id": "5ef51a6c7c74daa7004d4e23c62022b2",
        "permissions": ["admin"],
        "beneficialOwner": false
      }
    ],
    "organizations": [],
    "name": { "full": "Satoshi Nakamoto", "first": "Satoshi", "last": "Nakamoto" },
    "email": { "email": "nakamoto@bitcoin.com", "verified": true },
    "phone": { "phone": "", "verified": false },
    "country": "USA",
    "identity": {
      "kyc": {
        "failureCount": 0,
        "fullyRequired": false,
        "required": true,
        "available": true,
        "hasVideoID": false,
        "passport": { "required": false, "state": "unverified" },
        "isScreeningRequired": true,
        "data": {
          "state": "approved",
          "fields": {
            "country": "USA",
            "firstName": "Satoshi",
            "lastName": "Nakamoto",
            "dob": "19XX-XX-XX"
          }
        },
        "overallState": "approved",
        "documents": { "state": "unverified" },
        "residency": { "state": "unverified" }
      },
      "verified": false
    },
    "otpDevices": [
      {
        "id": "62ab917e4159d500079e5b836e41fba2",
        "createDate": "2022-06-16T20:24:30.000Z",
        "type": "totp",
        "label": "Google Authenticator",
        "verified": true,
        "lastValidatedDate": "2023-02-06T21:14:09.469Z",
        "scopes": []
      }
    ],
    "rateLimits": {},
    "disableReset2FA": false,
    "currency": { "currency": "USD", "bitcoinUnit": "BTC" },
    "timezone": "America/Los_Angeles",
    "isActive": true,
    "ecdhKeychain": "xpub661MyMwAqRbcG9rxFyVx56soHRSzi6kCD1GPwd838qDJ7piucKe8JYfBS4VVLChNHZytXUkWf8sQb5jjXC1abjdS968rJEDjJrGQu3qVsCP",
    "referrer": { "source": null, "campaign": null },
    "forceResetPassword": false,
    "allowedCoins": [],
    "agreements": {
      "termsOfUse": 1,
      "termsOfUseAcceptanceDate": "2022-06-16T20:24:33.159Z",
      "patriotAct": 0
    },
    "lastLogin": "2024-03-08T20:38:07.708Z",
    "featureFlags": [],
    "bitgoEmployee": false,
    "state": "California",
    "sourceVerificationRequiredForReadOnlyAccess": true
  }
}

2. Add Admins to Enterprises

Before you can add admins to your organization, you must first add them to your enterprise.

Endpoint: Add User to Enterprise

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
export ENTERPRISE_ID="YOUR_ENTERPRISE_ID"
export ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl -X POST \
  "https://app.bitgo-test.com/api/v2/enterprise/$ENTERPRISE_ID/user" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "permission": "admin",
    "usernames": [
        "user1@example.com",
        "user2@example.com",
        "user3@example.com",
    ]
}'

Step Result

You sent an email invitations to join your enterprise with an admin role.

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "id": "65eb7a68d35b5e7856e94fcc1f7a48bb",
  "enterprise": "62c5ae8174ac860007aff138a2d74df7",
  "creator": "62ab90e06dfda30007974f0a52a12995",
  "createDate": "2024-03-08T20:51:52.447Z",
  "info": {
    "type": "updateEnterpriseRequest",
    "updateEnterpriseRequest": {
      "action": "add",
      "email": "user2@bitcoin.com",
      "permissions": "admin",
      "userId": "5f063f7e319d6800263aff885de41fa0"
    }
  },
  "approvers": [],
  "state": "pending",
  "scope": "enterprise",
  "userIds": [
    "5543247a32d9b1f4037cfd782fc4b06d",
    "621d08a634ad8a0007fcddffd7c429cc",
    "627ff9325a5c1b0007c05a40d15e1522",
    "62ab90e06dfda30007974f0a52a12995"
  ],
  "approvalsRequired": 1,
  "singleRunResults": [],
  "resolvers": [],
  "actions": [],
  "resolutionOrder": []
}

Note: Ensure you select a number of admins to be video approvers. BitGo requires video approval for withdrawals that are valued greater than $250,000 USD.

3. Fetch Organization Details

BitGo uses your organization name and organization ID to link child enterprises together.

Endpoint: Get Enterprise

  • cURL
1
2
3
4
5
6
7
8
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X GET \
  "http://$BITGO_EXPRESS_HOST:3080/api/v2/enterprise/$ENTERPRISE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Step Result

The following response is abridged to highlight the organization details:

  • JSON
1
2
3
4
5
6
7
{
  "id": "62c5ae8174ac860007aff138a2d74df7", // your entperprise ID
  "name": "Prestige Worldwide", // your enterprise and organization name
  "type": "Other",
  "organizationId": "62c5ae8174ac860007aff1555ffb960d", // your organization ID
  "wallets": []
}

4. Add Organization Admins

Select enterprise admins that you want to make organization admins.

Currently, this can't be done programmatically. You must contact support@bitgo.com and request that specific enterprise admins be made organization admins.

Step Result

Your organization has admins that can create and manage child enterprises.

Next Steps

Set Up Child Enterprises

See Also