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.

By default, BitGo requires you to include IP-address or CIDR block restrictions for long-lived access tokens in the production environment. However, you can request an exception for tokens with read-only scopes (common for accounting, auditing, or reporting) by contacting [email protected].

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

1. Create Access Token

Endpoints: Create access token and Login

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export SCOPE="<SCOPE>"
export DURATION="<DURATION>"
export LABEL="<DESIRED_TOKEN_NAME>"
export IP_RESTRICT="<IP_ADDRESS_OR_CIDR_BLOCK>"
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
    }
  ]
}'

export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export EMAIL="<EMAIL_ADDRESS>"
export OTP="<OTP>"
export PASSWORD="<PASSWORD>"

curl -X POST \
  https://app.bitgo-test.com/api/v1/user/login \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "email": "'"$EMAIL"'",
  "otp": "'"$OTP"'", # OTP is always 000000 in test environment
  "password": "'"$PASSWORD"'"
}'

import { BitGoAPI } from '@bitgo/sdk-api';
const bitgo = new BitGoAPI({ env: 'test' });
const auth_res = await bitgo.authenticate({
  username: "[email protected]",
  password: process.env.PASS,
  otp: "000000",
});
const access_token = await bitgo.addAccessToken({
  otp: "000000",
  label: "Admin Access Token",
  scope: [
    "openid", // Verify your BitGo user ID
    "pending_approval_update", // Update pending approvals
    "profile", // View your BitGo profile
    "settlement_network_read", // Let's partners engage in allocations with clients
    "settlement_network_write", // Let's partners engage in allocations with clients
    "trade_trade", // Make trades
    "trade_view", // View trades
    "user_manage", // Manage your entire BitGo account
    "wallet_approve", // Approve transactions for a wallet
    "wallet_approve_all", // Approve transactions for all wallets
    "wallet_create", // Create wallets
    "wallet_edit", // Edit wallet comments
    "wallet_edit_all", // Edit comments for all wallets
    "wallet_edit_enterprise", // Edit enterprise comments
    "wallet_freeze", // Freeze a wallets
    "wallet_freeze_all", // Freeze all wallets
    "wallet_manage", // Manage settings for a wallet
    "wallet_manage_all", // Manage settings for all wallets (required to use webhooks)
    "wallet_manage_enterprise", // Manage enterprise settings
    "wallet_spend", // Send transactions from a wallet
    "wallet_spend_all", // Send transactions from a wallet
    "wallet_spend_enterprise", // Spend enterprise transactions
    "wallet_view", // View transactions for a wallet
    "wallet_view_all", // View transactions for all wallets
    "wallet_view_enterprise" // View enterprise transactions
    ],
  // Optional: Set a spending limit.
  spendingLimits: [
    {
      coin: "tbtc4",
      txValueLimit: "1000000000", // 10 TBTC4 (10 * 1e8)
    },
  ],
});
console.log(access_token);

bitgo.authenticate({ username: user, password: password, otp: '0000000' }).then(function (response) {
  var token = response.access_token;
  var user = response.user;
  // etc
});

Step Result

You receive an access token and an id for the token. Save this token for future use. This token is unrecoverable. If you lose it, you must make another.

{
  "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": "[email protected]",
    "email": {
      "email": "[email protected]",
      "verified": true
    },
    "phone": {
      "phone": "310-867-5309",
      "verified": true
    },
    "country": "USA",
    "state": "New York"
  }
}