HMAC Request Signing Guide

This guide explains how to sign HTTP requests using HMAC-SHA256 in JavaScript. 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

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

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.

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.

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)

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

Below are examples showing how to use the authentication headers with different HTTP methods and endpoints.

For GET requests without a body, pass null as the body parameter.

For POST/PUT requests, pass the JSON body to generate the signature.

Usage Examples