Authentication Headers
Three required headers on every signed request — x-api-key, x-timestamp, x-signature.
Every authenticated API call must include all three headers below. Missing or
invalid headers return 401 Missing API authentication headers.
| 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. |
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
METHOD | PATH | TIMESTAMP | BODY- Delimiter must be a literal pipe (
|), no surrounding whitespace. - Method must be uppercase (
POST,GET,DELETE). - 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.
Signature algorithm
HMAC-SHA256 with hex output. Use your signing key as the HMAC secret.
crypto.createHmac('sha256', apiSecret).update(canonical).digest('hex');