Authentication
Merchant API keys
Section titled “Merchant API keys”Authorization: Bearer sk_.... It names its merchant by itself, so it needs no other header, and it can act only for that one merchant.
Merchant and channel keys are secrets. Keep them server-only: never embed them
in JavaScript, mobile application packages, HTML, URLs, or browser requests.
Send the selected key in the Authorization header only from a trusted server.
Channel API keys
Section titled “Channel API keys”Authorization: Bearer sk_.... It belongs to the channel rather than to any one merchant: on a route that acts for a merchant it must be paired with the X-Merchant-Id header (ChannelMerchantId), and the merchant it names is served only if that merchant really belongs to the channel.
For a per-merchant call, the channel credential is paired with the header described by the contract:
The id of the merchant a channel API key is acting for. Required alongside a channel key on every per-merchant route — omitting it is a 401, not a default — and never valid on its own. A merchant key may also send it, but only naming its own merchant.
Derive merchant identity from your authenticated channel-side record. Do not accept an arbitrary merchant ID from an untrusted browser and forward it.
Channel key issuance
Section titled “Channel key issuance”A channel owner activates from the verified mailbox; that same authenticated browser receives the first working API key without a second email or administrator action. Activation creates the owner-session handoff in the same transaction and displays the key on the activation page. If the success response is lost, the same owner and device can recover the same key for 10 minutes without creating a second one.
Sandbox and production are separate backends. Each backend fixes the credential environment; neither the administrator nor the owner selects it. A replacement email is available only as recovery after activation, when that environment has no usable key and no live pending invitation.
Store the returned plaintext once and keep it on a trusted server. A channel
key has a nullable expires_at of null. Use POST /api/channel/api-keys for
later rotations and POST /api/channel/api-keys/{key_id}/revoke to retire a
key after its replacement is deployed.
Dashboard and buyer calls
Section titled “Dashboard and buyer calls”Dashboard bearer tokens represent signed-in users; they are not integration credentials. Some buyer-safe checkout operations declare an anonymous security alternative because the checkout session is the capability. Do not attach a secret key to those browser calls.
Current limits
Section titled “Current limits”API keys have no safe browser use and cannot be narrowed to one checkout. A
channel key cannot use merchant-only self-service routes, and it cannot scope a
merchant call without X-Merchant-Id. An invitation is not an API key and
cannot authenticate an integration request.