Skip to main content

​
Secret keys

Every request must include your secret key as a Bearer token: 
Authorization: Bearer sk_test_replace_me
The key prefix selects the environment:
PrefixEnvironmentNotes
sk_test_…TestFor use against staging.
sk_live_…LiveFor use against production.
On production, test keys are rejected. On staging, only live-style behaviour is served. Keep your secret keys server-side — never ship them in client apps or commit them to source control.

​
The customer-id header

Many routes act on behalf of a specific merchant customer (a buyer or seller you manage). These require a customer-id header alongside your secret key: 
Authorization: Bearer sk_test_replace_me
customer-id: 665f1b2c9a1e4d0012ab3c01
Routes that require customer-id include wallet, confirm-payment, milestone confirm, disputes (per-customer), payments, cards, and the crypto whitelist.
A few merchant-wide routes must not include a customer-id header — namely List all customers’ disputes, Get escrow feeds, and Resolve dispute & disburse. Sending one will scope the request incorrectly.

​
Merchant super-admin routes

Routes under Merchant Customers require the API key to belong to a merchant super-admin account. A regular customer key cannot create or manage other customers.

​
Common auth errors

StatusMessageCause
401No token providedMissing Authorization header.
401Access deniedKey is valid but not permitted for this action.
400customer-id header is requiredRoute needs a customer-id header.