Authentication and the signature
The canonical string rule, and how to compute it in curl, Node.js, Python and PHP.
There is no API key header and no session. Every request to every Atlas
endpoint is authenticated the same way: a signature field, computed from the
request body and your merchant secret.
signature is required
signature is a required field on every endpoint — never optional, and the two
ways of getting it wrong are refused differently:
- Absent, or an empty string. A
400, withmessageas an array of constraint failures namingsignature— the same answer as any other missing required field. Validation runs before anything looks at the signature, so the request never reaches the check. - Present but incorrect. A
401 invalid signature.
The 401 is deliberately uninformative, and that part is worth relying on: a
forged signature, a signature computed over a project that doesn't exist, and a
signature sent under an unknown merchant all produce exactly that response. It
can't be used to probe which identifiers exist.
The canonical string
- Take every field you send in the body, except
signature. - Drop any field whose value is empty or omitted — except an array, which is never dropped, empty ones included.
- Sort the remaining fields by field name, ascending.
- Take their values, in that sorted order, and join them with a single pipe
|. - Decode your merchant secret from hex to raw bytes, and use it as the HMAC key.
- The signature is the lower-case hex HMAC-SHA256 digest of that joined string.
Values are stringified before they're joined: a boolean becomes true or
false (lower-case), a number becomes its plain decimal text. This is why
sending 12 — an unquoted JSON number — for a field documented as a string
can produce a signature that validates and a request that doesn't: the
canonical string is identical either way, since signing stringifies both, but
the field's type is checked separately, and a bare number is not accepted
where a string is required.
An array stringifies as [first,second] — its members joined with commas, in
the order you send them — and [] when it's empty. Wherever a field can be an
array, that's the one exception to step 2: nothing else survives being empty.
Worked example
Secret (hex): 5f3a9c1e0b7d4826a1c9e2f6b8d0473c
Body fields, sorted by name (user_email is optional, and included here
because it was sent):
amount|callback_url|cancel_url|currency|failure_url|project|success_url|user_emailJoined message:
1.00|https://shop.example.com/callback|https://shop.example.com/cancel|USD|https://shop.example.com/failure|VxvcO2tgL9URWTIWGlgPB|https://shop.example.com/success|[email protected]Signature:
610cb7d5b70f23b49f1aa4d3000752c0030f0aa46f80b5546a5e9ffd1d0e805fGenerating the signature
SECRET_HEX="5f3a9c1e0b7d4826a1c9e2f6b8d0473c"
# Every non-empty body field except 'signature', values ordered by field name, joined with '|'
MESSAGE="1.00|https://shop.example.com/callback|https://shop.example.com/cancel|USD|https://shop.example.com/failure|VxvcO2tgL9URWTIWGlgPB|https://shop.example.com/success|[email protected]"
SIGNATURE=$(printf '%s' "$MESSAGE" \
| openssl dgst -sha256 -mac HMAC -macopt hexkey:$SECRET_HEX \
| awk '{print $2}')Each endpoint signs a different set of fields — always by this same rule, just over whatever that endpoint accepts. The reference page for each endpoint says which fields feed its signature; Payments and Payouts, refunds and status lookups walk through the ones with more than one or two.
Webhook deliveries are signed differently
The signature Atlas attaches to a webhook callback uses the same HMAC-SHA256-under-your-hex-decoded-merchant-secret construction, but sorts the values byte-wise rather than the field names — a different rule from every request you send. See Webhooks.