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:

1
BITNOB_CLIENT_IDstring

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

2
BITNOB_SECRET_KEYstring

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 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:

HeaderValuePurpose
x-auth-clientYour CLIENT_IDIdentifies who is calling the API
x-auth-timestampThe ISO 8601 timestampPrevents replay of old requests
x-auth-nonceThe UUID v4 nonceAdds per-request uniqueness
x-auth-signatureThe Base64 HMACVerifies 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.

Signed Fetch Function

Usage Example

Create Customer Example
Did you find this page useful?