GuidesAPI Reference
DocumentationLog In

Authorization and Authentication

Private Endpoints

Private endpoints are available for order management and account management. Every private request must be signed using the described authentication scheme.

πŸ“˜

Private endpoints require authentication using your Coinbase Exchange API key. You can generate API keys here.

Generating an API Key

To sign a request, you must create an API key via the Coinbase Exchange website.

The API key is scoped to a specific profile. Each user can generate a max of 300 API keys.

When creating a key, you must remember (and should write down) the following 3 pieces of information:

  • Key
  • Secret
  • Passphrase

The key and secret are randomly generated and provided by Coinbase Exchange; you choose a passphrase to further secure your API access.

❗

️ Warning

Coinbase Exchange stores the salted hash of your passphrase for verification and cannot be recovered if you forget it.

API Key Permissions

You can restrict the functionality of API keys. Before creating the key, you must choose what permissions you would like the key to have:

PermissionDescription
ViewKey has read permissions for all endpoints (including GET)
TransferKey can transfer value for accounts, including deposits/withdrawals (and bypasses 2FA)
TradeKey can post orders and get data

Refer to the documentation below to see what API key permissions are required for a specific route.

Creating a Request

All REST requests must contain the following headers:

HeaderDescription
CB-ACCESS-KEYAPI key as a string
CB-ACCESS-SIGNbase64-encoded signature (see Signing a Message)
CB-ACCESS-TIMESTAMPTimestamp for your request
CB-ACCESS-PASSPHRASEPassphrase you specified when creating the API key

All request bodies should have content type application/json and be valid JSON.

Signing a Message

The CB-ACCESS-SIGN header is generated by creating a sha256 HMAC using the base64-decoded secret key on the prehash string timestamp + method + requestPath + body (where + represents string concatenation) and base64-encode the output. The timestamp value is the same as the CB-ACCESS-TIMESTAMP header.

The body is the request body string, or it is omitted if there is no request body (typically for GET requests).

The method should be UPPER CASE.

πŸ“˜

Remember to base64-decode the alphanumeric secret string (resulting in 64 bytes) before using it as the key for HMAC. Also, base64-encode the digest output before sending in the header.

var crypto = require('crypto');

var cb_access_timestamp = Date.now() / 1000; // in ms
var cb_access_passphrase = '...';
var secret = 'PYPd1Hv4J6/7x...';
var requestPath = '/orders';
var body = JSON.stringify({
    price: '1.0',
    size: '1.0',
    side: 'buy',
    product_id: 'BTC-USD'
});
var method = 'POST';

// create the prehash string by concatenating required parts
var message = cb_access_timestamp + method + requestPath + body;

// decode the base64 secret
var key = Buffer(secret, 'base64');

// create a sha256 hmac with the secret
var hmac = crypto.createHmac('sha256', key);

// sign the require message with the hmac
// and finally base64 encode the result
var cb_access_sign = hmac.update(message).digest('base64');

Selecting a Timestamp

The CB-ACCESS-TIMESTAMP header MUST be number of seconds since Unix Epoch in UTC. Decimal values are allowed.

Your timestamp must be within 30 seconds of the API service time or your request is considered expired and rejected. We recommend using the time endpoint to query for the API server time if you believe there is a time difference between your server and the API servers.