Authentication Headers

Every authenticated API call must include signed HMAC headers. Missing or invalid headers return an unauthenticated response.

Route version and signing version

All merchant API routes use /v1/... URLs. HMAC v1 and HMAC v2 are signing formats for those routes, not separate endpoint namespaces.

Do not change /v1/payouts to /v2/payouts. To use HMAC v2, keep the /v1 URL and add x-bridg-sig-version: 2 with the v2 headers below.

HMAC v1 headers

Use HMAC v1 only for legacy requests without query strings.

Header	Description
x-api-key	Your public API key (e.g. pub_asterfield_001). Identifies which merchant is calling.
x-timestamp	Unix epoch milliseconds as a string: Date.now().toString().
x-signature	HMAC-SHA256 hex signature over the canonical request string. See Generate Signature.

HMAC v2 headers

Use HMAC v2 for new integrations and for any endpoint with query parameters. The request path still starts with /v1.

Header	Description
x-bridg-sig-version	Must be 2.
x-api-key	Your public API key.
x-timestamp	Unix epoch milliseconds as a string.
x-nonce	Unique value per request, usually a UUID. Replays are rejected.
x-signature	HMAC-SHA256 hex signature over the v2 canonical request string.

Timestamp rules

• Format: Unix epoch milliseconds (string)
• Validity: ±5 minutes from server time

Requests outside the window are rejected. Sync your server clock via NTP.

Canonical request format

HMAC v1:

METHOD | PATH | TIMESTAMP | BODY

• Delimiter must be a literal pipe (|), no surrounding whitespace.
• Method must be uppercase (POST, GET, DELETE).
• Requests with a non-empty query string must use v2 signing.
• For GET/DELETE/HEAD/OPTIONS: BODY is the empty string.
• For POST/PUT/PATCH: BODY is the exact JSON bytes you'll send on the wire — do not re-serialise after signing.

HMAC v2:

METHOD | HOST | PATH_AND_QUERY | API_KEY | TIMESTAMP | NONCE | SHA256_HEX(BODY)

See API Keys and IP Whitelist for the v2 example.

Signature algorithm

HMAC-SHA256 with hex output. Use your signing key as the HMAC secret.

crypto.createHmac('sha256', apiSecret).update(canonical).digest('hex');