Ctrl+K

Create Access Tokens

Overview

Access tokens enable you to authenticate a session with BitGo and are either short lived (2 hours) or long lived (up to 10 years). Short-lived access tokens require a one-time password (OTP) for sensitive operations, such as withdrawals. Long-lived access tokens enable you to interact with BitGo APIs without an OTP, and are therefore better suited for integrations.

In the production environment, by default, you must restrict long-lived access to specific IP-addresses. However, you can bypass this requirement for access tokens with read-ony scopes (for things like auditing, accounting, or reporting) by contacting support@bitgo.com.

Best Practices

BitGo recommends the following to manage your access tokens:

  • Use long-lived access tokens for your integration.
  • Rotate your tokens frequently - don't let them last 10 years.
  • Include a spending limit. If you omit a spending limit, you must unlock the access token on a regular basis to permit sensitive operations, such as withdrawals.
  • Practice the principle of least privilege (POLP) by assigning the fewest scopes necessary for an access token to perform its intended function.
  • Manage your enterprise users in the BitGo web application, instead of programmatically, since user management can only be done with short-lived access token (with the user_manage scope).

Passphrases

You can configure BitGo wallets to use passphrases when spending. For administrators who create access tokens, note the following:

  • If you create the access token and the wallet, use the wallet passphrase to transact from the wallet (this may also be your BitGo-login passphrase).
  • If you create the access token but someone else creates a wallet, use your BitGo-login passphrase to transact from the wallet.

Prerequisites

Sign up for a BitGo account.

1. Create Access Token

Endpoints: Create access token and Login

  • cURL (long lived)
  • cURL (short lived)
  • JavaScript (long lived)
  • JavaScript (short lived)
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
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export SCOPE="<SCOPE>"
export DURATION="<DURATION>"
export LABEL="<DESIRED_TOKEN_NAME>"
export IP_RESTRICT="<IP_ADDRESS>"
export ENTERPRISE="<YOUR_ENTERPRISE_ID>"
export COIN="<ASSET_ID>"
export TX_VALUE_LIMIT="<TX_VALUE_LIMIT>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/user/accesstoken \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "scope": ["'"$SCOPE"'"],
  "duration": "'"$DURATION"'",
  "label": "'"$LABEL"'",
  "admin": false,
  "ipRestrict": ["'"$IP_RESTRICT"'"],
  "enterprise": "'"$ENTERPRISE"'",
  "spendingLimits": [
    {
      "coin": "'"$COIN"'",
      "txValueLimit": "'"$TX_VALUE_LIMIT"'",
      "maxLimit": false
    }
  ]
}'

Step Result

You receive an access token and an id for the token. Save this token for future use. If you lose this token, you can't recover it and must make another.

  • 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
{
  "access_token": "9b72c68ef394f5146f0f3efc1feafb7a971752cb00e79fafcfd8c1d2db83639c",
  "expires_at": 1534201288,
  "scope": [
    "user_manage",
    "openid",
    "profile",
    "wallet_create",
    "wallet_manage_all",
    "wallet_approve_all",
    "wallet_spend_all",
    "wallet_edit_all",
    "wallet_view_all"
  ],
  "user": {
    "id": "59cd72485007a239fb00282ed480da1f",
    "isActive": true,
    "name": {
      "first": "Jane",
      "full": "Jane Doe",
      "last": "Doe"
    },
    "username": "user@example.com",
    "email": {
      "email": "user@example.com",
      "verified": true
    },
    "phone": {
      "phone": "310-867-5309",
      "verified": true
    },
    "country": "USA",
    "state": "New York"
  }
}

See Also