Ctrl+K

Hash-Based Message Authentication Code (HMAC)

BitGo access tokens (V2 and later) uses hash-based message authentication code (HMAC) to validate communication between your app and BitGo. HMAC is a hashing function that prevents man-in-the-middle attacks by mathematically checking for tampered requests. The BitGo JavaScript SDK automatically generates HMAC values on all your outgoing communications to BitGo, passing details such as:

  • Access token
  • Body parameters
  • Current time
  • URL and method

After receiving a request with an HMAC header, BitGo runs a similar hashing function that confirms that all the data is tamper free.

HMAC Construction

When making requests directly to BitGo APIs, you must manually construct the HMAC header.

For V2 access tokens, HMAC headers require the following (in this order):

  • The current time as a Unix epoch timestamp under the Auth-Timestamp header.
  • The URL path under the X-Original-Uri header.
  • The body parameters, either attached to the request or under the X-Original-Body header.

For V3 access tokens, HMAC headers require the following (in this order):

  • The HTTP request method in all capital letters (GET, PUT, POST, and so on).
  • The current time as a Unix epoch timestamp under the Auth-Timestamp header.
  • The version of the access token (in this case 3.0) under the Bitgo-Auth-Version header.
  • The URL path under the X-Original-Uri header.
  • The body parameters, either attached to the request or under the X-Original-Body header.

You must concatenate these values into a single string, separating them with the vertical bar (|) character. Then, you must hash this value using SHA256 with your access token as the key to get your HMAC header.

Common Errors:

  1. Incorrectly serializing the request body. For example, GET request bodies should be an empty string that's passed to the HMAC calculation. For all other HTTP methods, the request bodies passed to the HMAC calculation should be the string literal of an empty JSON ({}).
  2. Passing a full URL instead of only the URL path. For example, setting X-Original-Uri to https://abc.com/test/123 instead of /test/123.
  3. Omitting the version of the BitGo access token. For example, forgetting to set the Bitgo-Auth-Version header to the correct version (2.0 for V2 access tokens and 3.0 for V3 access tokens).

See Also

Create Access Tokens