Authentication
Every Public API request authenticates with an API key in the Authorization header.
Header
Authorization: Bearer cnk_live_4f2d8c91e5b34a7f9e6c2d1a8b5f7e3c
A missing, malformed, unknown, or revoked key returns 401 Unauthorized. The error body deliberately omits the reason — it's a credential check, not a debugging aid.
Token format
API keys are formatted as cnk_live_<random> — the cnk_live_ prefix followed by a random string. The prefix is informational; the server validates the full token.
Scopes
Every key carries a list of scopes that constrain which endpoints it can call. An endpoint that requires a scope your key doesn't have returns 403 Forbidden — the response data lists which scopes were required and which you held.
| Scope | Grants |
|---|---|
* |
Full access — every endpoint. Reserve for trusted internal scripts. |
account:read / account:write |
Account profile. |
inventory:read / inventory:write |
Stock state. |
listings:read / listings:write |
Public marketplace listings. |
sales:read / sales:write |
Outgoing orders (you as seller). |
purchases:read / purchases:write |
Incoming orders (you as buyer). |
disputes:read / disputes:write |
Disputes. |
messaging:read / messaging:write |
Buyer/seller conversations. |
pricing:read / products:read |
Catalogue and pricing data. |
financial:read |
Balances and payouts. |
marketplace:read |
Cross-cutting marketplace metadata. |
Mint keys with the narrowest scope set the integration needs. You can always issue a new key later if requirements expand.
Identity
A key is bound to a single CardNexus account. Multiple keys per account are encouraged — one per integration — so revoking one doesn't take down the others.
Rotating
If a key leaks, revoke it from Settings → API keys. Revocation takes effect on the next request; there's no grace period.
For zero-downtime rotation: mint a new key, deploy it, verify with GET /v1/account/me, then revoke the old one.