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, settings and vacation mode. |
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. |
financial:read |
Balances and payouts. |
Catalogue, pricing, and feed endpoints need no scope — any valid key can read them.
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.
OAuth for AI assistants
The CardNexus MCP server, which connects AI assistants to an account, signs people in with OAuth instead of an API key. The assistant receives a token (cno_…) that works only on the MCP server, at https://mcp.cardnexus.com/mcp, and is limited to the permissions the account chose when it connected. A cno_ token sent to a /v1 endpoint returns 401 Unauthorized, and an API key does not work on the MCP server. See AI assistants.
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.