Authentication

🤖 Building with an AI agent? Point your assistant at llms.txt (a concise index) or llms-full.txt (the complete spec in a single file) — both are written for LLMs to scaffold an integration end-to-end.

Generating the HMAC Signature

All requests to the API must include an X-Hmac-Signature header that contains your Partner ID and an HMAC signature of the request body. The signature is generated using the HMAC SHA512 algorithm, with the partner’s secret API key as the HMAC key.

X-Hmac-Signature: <partnerId>:<signature>

• <partnerId> is your partner identifier (issued to you by vinieta.md).
• <signature> is the lowercase hex digest of HMAC-SHA512(rawRequestBody, partnerSecret), where partnerSecret is your secret API key (also issued by vinieta.md).
• The HMAC key is your partnerSecret. The HMAC message is the exact raw JSON body string you send — the same bytes the server receives.

The API uses the X-Hmac-Signature header to verify that the request has not been tampered with and is from an authorized partner. Requests missing the HMAC signature or with an invalid signature will be rejected.

Failure modes you must handle:

Code	Cause
401	Header missing entirely
403	Header present but signature invalid (wrong secret, wrong partnerId, re-serialized body)

Sign the bytes you transmit

Serialize your JSON once, sign that string, and send that same string. Do not re-serialize differently after signing, or the signature will not match. The safest pattern is const raw = JSON.stringify(body) — sign raw, then send raw as the HTTP body. Keep attribute order stable between signing and sending.

Examples

To generate the signature in code:

JS Example

const crypto = require('crypto');

const body = {...}; // JSON attributes in doc order
const secret = '...';
const partnerId = '...';

const hmac = crypto.createHmac('sha512', secret);
hmac.update(JSON.stringify(body));

const signature = hmac.digest('hex');

request.headers['X-Hmac-Signature'] = `${partnerId}:${signature}`;

PHP Example

$body = ['...']; // JSON attributes in doc order
$secret = '...';
$partnerId = '...';

$hmac = hash_hmac('sha512', json_encode($body), $secret);

$headers['X-Hmac-Signature'] = $partnerId . ':' . $hmac;

Python Example

import hashlib
import hmac as hmac_lib
import json

body = {...} # JSON attributes in doc order
secret = '...'
partner_id = '...'

signature = hmac_lib.new(
    secret.encode(),
    json.dumps(body).encode('utf-8'),
    hashlib.sha512,
).hexdigest()

headers = {'X-Hmac-Signature': partner_id + ':' + signature}

The canonical algorithm is a keyed HMAC-SHA512 over the serialized body, hex-encoded. Match the output of the JS and PHP snippets above.

Postman Pre-request Script

JS Example

const message = JSON.stringify(JSON.parse(pm.request.body.raw));
const secret = "...";
const partnerId = "...";
const hashHmacSHA512 = CryptoJS.HmacSHA512(message, secret).toString();

pm.request.headers.add(`x-hmac-signature:${partnerId}:${hashHmacSHA512}`);

Next: the Quickstart walks the full order lifecycle end to end.