HMAC Request Signing Guide
This guide explains how to sign HTTP requests using HMAC-SHA256 in plain JavaScript with fetch. All examples assume a Node.js v18+ environment (native fetch, crypto.randomUUID().).
Prerequisites
Node.js v18+ (for native fetch and crypto.randomUUID() ) Environment variables set:
Your Bitnob Client ID used to authenticate API requests. This is provided by Bitnob when you create an app.
Your Bitnob Secret Key used for signing API requests. Keep this key secure and do not expose it in frontend code.
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 cryptographically-random UUID v4 string. Guarantees each request is one-off and thwarts replay attacks.
Timestamp The current UTC date/time in ISO 8601 format (e.g.2025-06-24T14:31:05Z ). Ensures you can reject stale requests.
Build the Canonical Message
Concatenate the following fields in exactly this order (no delimiters):
CLIENT_ID + HTTP_METHOD + REQUEST_URL + TIMESTAMP + NONCE + BODY_STRING
Normalize Convert the entire concatenated string to lowercase.
Why? Guarantees a consistent input to the signer, regardless of casing in URLs or JSON body.
Body_String should be the exact JSON (or form-encoded) payload you're sending—without extra whitespace or line breaks.
Compute the Signature
Use HMAC-SHA256 over the normalized message, keyed with your shared SECRET_KEY.
Encode the raw binary HMAC output in Base64.
Example pseudo-code:
plaintext message = lowercase(concat(...)) raw_hmac = HMAC_SHA256(message, SECRET_KEY) signature = Base64Encode(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 | The ISO 8601 timestamp | Prevents replay of old requests |
x-auth-nonce | The UUID v4 nonce | Adds per-request uniqueness |
x-auth-signature | The Base64 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.
Usage Example