Skip to main content
Every v2 request sends your key as a bearer token:
The only endpoint that takes no key is the public token metadata, which wallets and marketplaces read.

Base URL and formats

  • Base URL: https://catchbackcards.com/api/partner/v2.
  • Formats: JSON, UTF-8. Money is USD in dollars (25, 9.85).
  • New fields can appear at any time. Ignore fields you don’t recognize.
  • OpenAPI spec: the OpenAPI 3.1 spec is the official contract, with every endpoint, error code and webhook event. Generate your client from it: https://catchbackcards.mintlify.app/partner-api/v2/openapi.yaml.

Scope and program

  • Scope: every v2 endpoint needs the scope nft:orders on your key.
  • Program: your key is linked to your partner program, which fixes the chain your NFTs mint on (mint_chain) and your collection contract. Every endpoint acts within your program: an order, token, quote or shipment from another program answers 404.

Errors every endpoint can return first

These come before an endpoint does anything else:

Read the key

GET /keys returns the key you call with: its id, name, scopes, dates, program, the key it replaced (rotated_from) and, once rotated, its successor and expires_at. It never returns a secret.

Rotate

POST /keys/rotate issues a new key for the same program, with the same scopes. No body; an Idempotency-Key is required.
  • The old key keeps working for 24 hours (previous_key.expires_at), then answers 401. Move every server to the new key within that window.
  • Store key.secret straight away. If the response is lost, call again with the same old key and the same Idempotency-Key within 10 minutes, before you use the new key: you get the same new key and secret back. After that (or once the new key has made a call) the replay is 409 ALREADY_ROTATED, so a leaked old key can never fetch the new one.
  • A key is rotated once. Rotating it again with a different Idempotency-Key is 409 ALREADY_ROTATED, with the successor; rotate the new key next time.
  • Your webhook moves with the rotation. The new key takes over the old key’s webhook (same URL, same secret), and the old key’s stops, so deliveries never pause and you change nothing.
  • A key that has been rotated can’t register or re-enable a webhook (409 KEY_ROTATED).

End the old key now

POST /keys/revoke-previous, called with the new key once every server uses it, ends the key it replaced immediately instead of at the end of the 24 hours, and its webhook stops with it. Do this whenever you rotate because a key may have leaked.

Handling

Keep the key server-side only: never in browser, app or wallet code.
  • If it leaks: rotate, move your servers to the new key, call POST /keys/revoke-previous, and tell us. Disabling a key on our side also disables every key rotated from it, so a leaked key that was rotated by someone else is shut off too.
  • Use a separate key per environment (sandbox, production).