Authentication

All API requests are made against the Bitnob base URL and authenticated using HMAC signature.

Base URL

Auth Modes

All API requests must be authenticated using HMAC Signature. Both your CLIENT_ID and CLIENT_SECRET are required.

HMAC Signature — Each request is signed with a timestamp and nonce, making it tamper-proof and resistant to replay attacks.

mode	headers required
HMAC Signature	X-Auth-Client, X-Auth-Signature, X-Auth-Timestamp, X-Auth-Nonce

HMAC Request Signing

This guide explains how to sign HTTP requests using HMAC-SHA256. All examples use Node.js with the built-in crypto module.

Prerequisites

Node.js with the built-in crypto module. Environment variables set:

CLIENT_IDstring

Your Bitnob Client ID used to authenticate API requests. This is provided by Bitnob when you create an app.

CLIENT_SECRETstring

Your Bitnob Secret Key used for signing API requests. Keep this key secure and do not expose it in frontend code.

Set Environment Variables

Setup the Signing Function

How It Works

This authentication flow ensures each request is fresh, tamper-proof, and uniquely identifiable.

Generate a Nonce & Timestamp

Nonce A 16-byte cryptographically-random value, hex-encoded. Guarantees each request is one-off and thwarts replay attacks.

Timestamp The current Unix timestamp in seconds (e.g.1719236465 ). Ensures you can reject stale requests.

Build the Canonical Message

Concatenate the following fields in exactly this order, separated by colons:

CLIENT_ID:TIMESTAMP:NONCE:PAYLOAD

Payload should be the exact JSON payload you're sending—without extra whitespace or line breaks. If no body, use an empty string.

Compute the Signature

Use HMAC-SHA256 over the string to sign, keyed with your shared CLIENT_SECRET.

Encode the raw binary HMAC output in hexadecimal.

Example pseudo-code:

plaintext stringToSign = CLIENT_ID:TIMESTAMP:NONCE:PAYLOAD raw_hmac = HMAC_SHA256(stringToSign, CLIENT_SECRET) signature = HexEncode(raw_hmac)

Attach the Authentication Headers

Include all four custom headers on every API request:

header	value	purpose
X-Auth-Client	Your CLIENT_ID	Identifies who is calling the API
X-Auth-Timestamp	Unix timestamp in seconds	Prevents replay of old requests
X-Auth-Nonce	16-byte hex-encoded nonce	Adds per-request uniqueness
X-Auth-Signature	The hex-encoded HMAC	Verifies integrity & authenticity

Tip: Always validate on the server that:

The timestamp is within an acceptable window (e.g. ±5 minutes).

The nonce hasn't been used before (store recent nonces for de-duplication).

The computed signature matches the one provided.

By following these steps exactly, you ensure your API is resilient against replay, tampering, and impersonation.

Auth

Usage Examples

These examples show how to make authenticated requests to the Bitnob API using the signing function defined above. The base URL https://api.bitnob.com is used for all requests.

GET Request (No Body)

For GET requests without a body, pass null as the body parameter. The signature is computed over just your client ID, timestamp, and nonce.

POST Request (With Body)

For POST/PUT requests, pass the JSON body to generate the signature. The body is included in the HMAC computation, so any change to the payload will invalidate the signature.

Note

Use the /api/whoami endpoint to quickly verify your authentication is set up correctly before making other API calls.

Usage Examples

Validate Authentication

Use the /api/whoami endpoint to verify your credentials are working correctly. This endpoint accepts any HTTP method and any payload, and returns your authenticated client info.

It works with HMAC signature authentication.

Response Fields

authenticatedboolean

Whether the request was successfully authenticated.

auth_methodstring

The authentication mode used: 'hmac'.

client_idstring

Your authenticated client ID.

client_namestring

The name associated with your client.

active_company_idstring

The company ID linked to this client.

environmentstring

The current environment: 'live' or 'sandbox'.

permissionsarray

List of permissions granted to this client.

activeboolean

Whether the client is currently active.

metadataobject

Any metadata associated with the client.

rate_limitobject

Rate limit details including requests_per_minute, requests_per_hour, and burst_size.

timestampstring

ISO 8601 timestamp of when the request was processed.

Validate Authentication

Response