Signing API Calls

Overview

This document walks through the various steps of generating keys for usage in the APIs to provide foundational knowledge whether you will use the prebuilt SDKs or not. If you choose not to use the prebuilt SDKs, you could import the language-specific key util to your project and implement your own API calls.

If you do prefer to use the pre-built SDKs, each SDK has a command-line setup utility that will generate keys as well as a configuration. The configuration file is almost identical across all SDKs and has the following JSON structure:

{
  "BitPayConfiguration": {
    "Environment": "",
    "EnvConfig": {
      "Test": {
        "PrivateKeyPath": "",
        "PrivateKey": "",
        "ApiTokens": {
          "merchant": "",
          "payout": ""
        }
      },
      "Prod": {
        "PrivateKeyPath": "",
        "PrivateKey": "",
        "ApiTokens": {
          "merchant": "",
          "payout": ""
        }
      }
    }
  }
}

In each EnvConfig, you can load your private key in one of two ways:

It is imperative that security be taken into account when storing your private key. BitPay strongly advises using a secrets manager or other encryption mechanism such as Mozilla SOPS. Examples of secrets managers are:

• AWS Secrets Manager
• Azure Key Vault
• GCP Secret Manager
• Hashicorp Vault

Key Utilities

BitPay has a key utility repository for most supported languages, with implementation and examples of key generation implementation and usage:

Generate Private Key

First, you’ll need to create your token if you haven’t already. See the notes at the top of this document regarding storage.

Generate Public Key

Once you have a private key, you will need to generate a public key.

Get SIN from Public Key

Once we have a public key, we’ll be able to generate the SIN

Generate x-identity Header

Use the public key to generate a hex string that can be used as the x-identity header.

Generate x-signature Header

Use the private key to sign the concatenated resource URL and JSON-encoded POST body.

Request: Generate Token

You’ll now have everything needed to call the /token endpoint to generate a token. The process is the same for all languages:

1. Create cURL call
   1. Headers
      1. x-accept-version: 2.0.0
      2. Content-Type: application/json
      3. x-identity: See above
      4. x-signature: See above
   2. Body (JSON-encoded)
      1. id = SIN
      2. facade = Name of facade, such as merchant
      3. label = (Optional) label you want to call the token

{
    "id": "Tf3qJ2Upet2cPnAMNJxa7k5JZvLPE93hhf7",
    "label": "My first token",
    "facade": "merchant"
}

Enter Pairing Code to Approve Token

Step	Screenshot
Log into your test or live account
Go to Payment Tools > API Tokens
Enter your pairing code from the response of your token request
Add a label if desired as well as your two-factor code Note: The token in the screenshot is just an example in the test environment, and has not been approved.