The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.
Every v2 request sends your key as a bearer token:
Authorization: Bearer cb_live_...
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:
Status
code
When
401
Missing or malformed API key (no Bearer cb_live_... header) or Invalid API key (unknown, disabled, or a rotated key past its 24 hours)
403
API key lacks required scope: nft:orders
429
RATE_LIMITED
Too many requests from this key (limits); the body has retry_after_seconds and the response a Retry-After header
403
NO_PROGRAM
The key isn’t linked to a partner program
403
PROGRAM_INACTIVE
Your program is not live
403
NOT_AVAILABLE
Wallet orders aren’t switched on for your program yet
503
AUTH_UNAVAILABLE
We couldn’t check your key right now (never means the key is bad); retry after Retry-After
503
We couldn’t load your program; retry shortly
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).
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"CatchBack Documentation","colors":{"primary":"#16A34A","light":"#07C983","dark":"#15803D"},"logo":{"light":"https://mintcdn.com/catchbackcards/t6yI8GaEaBqQQEpE/logo/catchback_logo_dark.png?fit=max\u0026auto=format\u0026n=t6yI8GaEaBqQQEpE\u0026q=85\u0026s=c0a46c19893e31a50cd0f4716d47686b","dark":"https://mintcdn.com/catchbackcards/t6yI8GaEaBqQQEpE/logo/catchback_logo_white.png?fit=max\u0026auto=format\u0026n=t6yI8GaEaBqQQEpE\u0026q=85\u0026s=e3c457633020dab4b98738040c7ae111"},"favicon":"https://mintcdn.com/catchbackcards/t6yI8GaEaBqQQEpE/logo/catchback_logo_dark.png?fit=max\u0026auto=format\u0026n=t6yI8GaEaBqQQEpE\u0026q=85\u0026s=c0a46c19893e31a50cd0f4716d47686b","api":{"playground":{"display":"simple"},"mdx":{"auth":{"method":"bearer"},"server":"https://catchbackcards.com"}},"appearance":{"default":"dark"},"navbar":{"links":[{"href":"mailto:support@catchbackcards.com","label":"Support"}],"primary":{"type":"button","label":"Launch App","href":"https://catchbackcards.com"}},"footer":{"socials":{"x":"https://x.com/catchback_cards","instagram":"https://www.instagram.com/catchback_cards","discord":"https://discord.gg/6WjMbRgPMq"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"metadata":{"timestamp":false},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"CatchBack Website","icon":"globe","href":"https://catchbackcards.com"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"catchbackcards","hasAudioNarration":false,"actualSubdomain":"catchbackcards","customDomains":[],"gitSource":{"type":"github","owner":"josephhhzhanggg","repo":"catchback-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6afd1c63365759e98bf2eec9","clientVersion":"0.0.4177","searchFilterCounts":[{"language":"default","tag":"Partner API","count":47},{"language":"default","tag":"API Reference","count":35},{"language":"default","tag":"Documentation","count":21},{"language":"default","tag":"Shipments","count":14},{"language":"default","tag":"Concepts","count":11},{"language":"default","tag":"Keys \u0026 revenue","count":8},{"language":"default","tag":"Features","count":7},{"language":"default","tag":"Resources","count":7},{"language":"default","tag":"Packs \u0026 orders","count":6},{"language":"default","tag":"Tokens \u0026 sell-back","count":6}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"partner-api/v2/authentication","slug":"/partner-api/v2/authentication","pageMetadata":{"title":"Authentication and keys","description":"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.","href":"/partner-api/v2/authentication"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Every v2 request sends your key as a bearer token:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`http`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`http`,children:_jsxs(_components.code,{language:`http`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#569CD6`},children:`Authorization`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` Bearer cb_live_...`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The only endpoint that takes no key is the `,_jsx(_components.a,{href:`/partner-api/v2/endpoints/get-token-metadata`,children:`public token metadata`}),`, which wallets and marketplaces read.`]}),`\n`,_jsx(Heading,{level:`2`,id:`base-url-and-formats`,children:`Base URL and formats`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Base URL:`}),` `,_jsx(_components.code,{children:`https://catchbackcards.com/api/partner/v2`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Formats:`}),` JSON, UTF-8. Money is USD in dollars (`,_jsx(_components.code,{children:`25`}),`, `,_jsx(_components.code,{children:`9.85`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`New fields can appear at any time.`}),` Ignore fields you don’t recognize.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`OpenAPI spec:`}),` the OpenAPI 3.1 spec is the official contract, with every endpoint, error code and webhook event. Generate your client from it: `,_jsx(_components.code,{children:`https://catchbackcards.mintlify.app/partner-api/v2/openapi.yaml`}),`.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`scope-and-program`,children:`Scope and program`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Scope:`}),` every v2 endpoint needs the scope `,_jsx(_components.code,{children:`nft:orders`}),` on your key.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Program:`}),` your key is linked to your partner program, which fixes the chain your NFTs mint on (`,_jsx(_components.code,{children:`mint_chain`}),`) and your collection contract. Every endpoint acts within your program: an order, token, quote or shipment from another program answers `,_jsx(_components.code,{children:`404`}),`.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`errors-every-endpoint-can-return-first`,children:`Errors every endpoint can return first`}),`\n`,_jsx(_components.p,{children:`These come before an endpoint does anything else:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:_jsx(_components.code,{children:`code`})}),_jsx(_components.th,{children:`When`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`401`})}),_jsx(_components.td,{}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`Missing or malformed API key`}),` (no `,_jsx(_components.code,{children:`Bearer cb_live_...`}),` header) or `,_jsx(_components.code,{children:`Invalid API key`}),` (unknown, disabled, or a rotated key past its 24 hours)`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`403`})}),_jsx(_components.td,{}),_jsx(_components.td,{children:_jsx(_components.code,{children:`API key lacks required scope: nft:orders`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`429`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`RATE_LIMITED`})}),_jsxs(_components.td,{children:[`Too many requests from this key (`,_jsx(_components.a,{href:`/partner-api/v2/limits-and-compliance`,children:`limits`}),`); the body has `,_jsx(_components.code,{children:`retry_after_seconds`}),` and the response a `,_jsx(_components.code,{children:`Retry-After`}),` header`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`403`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`NO_PROGRAM`})}),_jsx(_components.td,{children:`The key isn’t linked to a partner program`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`403`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`PROGRAM_INACTIVE`})}),_jsx(_components.td,{children:`Your program is not live`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`403`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`NOT_AVAILABLE`})}),_jsx(_components.td,{children:`Wallet orders aren’t switched on for your program yet`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`503`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`AUTH_UNAVAILABLE`})}),_jsxs(_components.td,{children:[`We couldn’t check your key right now (never means the key is bad); retry after `,_jsx(_components.code,{children:`Retry-After`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{\"data-numeric\":`true`,children:_jsx(_components.code,{children:`503`})}),_jsx(_components.td,{}),_jsx(_components.td,{children:`We couldn’t load your program; retry shortly`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`read-the-key`,children:`Read the key`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.a,{href:`/partner-api/v2/endpoints/get-key`,children:_jsx(_components.code,{children:`GET /keys`})}),` returns the key you call with: its `,_jsx(_components.code,{children:`id`}),`, `,_jsx(_components.code,{children:`name`}),`, `,_jsx(_components.code,{children:`scopes`}),`, dates, `,_jsx(_components.code,{children:`program`}),`, the key it replaced (`,_jsx(_components.code,{children:`rotated_from`}),`) and, once rotated, its `,_jsx(_components.code,{children:`successor`}),` and `,_jsx(_components.code,{children:`expires_at`}),`. It never returns a secret.`]}),`\n`,_jsx(Heading,{level:`2`,id:`rotate`,children:`Rotate`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.a,{href:`/partner-api/v2/endpoints/rotate-key`,children:_jsx(_components.code,{children:`POST /keys/rotate`})}),` issues a new key for the same program, with the same scopes. No body; an `,_jsx(_components.code,{children:`Idempotency-Key`}),` is required.`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`The old key keeps working for 24 hours`}),` (`,_jsx(_components.code,{children:`previous_key.expires_at`}),`), then answers `,_jsx(_components.code,{children:`401`}),`. Move every server to the new key within that window.`]}),`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[`Store `,_jsx(_components.code,{children:`key.secret`}),` straight away.`]}),` If the response is lost, call again with the same old key and the same `,_jsx(_components.code,{children:`Idempotency-Key`}),` within `,_jsx(_components.strong,{children:`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 `,_jsx(_components.code,{children:`409 ALREADY_ROTATED`}),`, so a leaked old key can never fetch the new one.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`A key is rotated once.`}),` Rotating it again with a different `,_jsx(_components.code,{children:`Idempotency-Key`}),` is `,_jsx(_components.code,{children:`409 ALREADY_ROTATED`}),`, with the `,_jsx(_components.code,{children:`successor`}),`; rotate the new key next time.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`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.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`A key that has been rotated can’t register or re-enable a webhook`}),` (`,_jsx(_components.code,{children:`409 KEY_ROTATED`}),`).`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`end-the-old-key-now`,children:`End the old key now`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.a,{href:`/partner-api/v2/endpoints/revoke-previous-key`,children:_jsx(_components.code,{children:`POST /keys/revoke-previous`})}),`, called with the `,_jsx(_components.strong,{children:`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.`]}),`\n`,_jsx(Heading,{level:`2`,id:`handling`,children:`Handling`}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`Keep the key server-side only: never in browser, app or wallet code.`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`If it leaks: rotate, move your servers to the new key, call `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsx(_components.li,{children:`Use a separate key per environment (sandbox, production).`}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Authentication and keys","description":"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.","href":"/partner-api/v2/authentication"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Base URL and formats","slug":"base-url-and-formats","depth":2,"children":[]},{"title":"Scope and program","slug":"scope-and-program","depth":2,"children":[]},{"title":"Errors every endpoint can return first","slug":"errors-every-endpoint-can-return-first","depth":2,"children":[]},{"title":"Read the key","slug":"read-the-key","depth":2,"children":[]},{"title":"Rotate","slug":"rotate","depth":2,"children":[]},{"title":"End the old key now","slug":"end-the-old-key-now","depth":2,"children":[]},{"title":"Handling","slug":"handling","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"catchbackcards","siteName":"CatchBack Documentation","title":"Authentication and keys - CatchBack Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-18T02:02:13.147Z","originalFileLocation":"partner-api/v2/authentication.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.\">\u003cmeta data-mint-head name=\"application-name\" content=\"CatchBack Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Authentication and keys - CatchBack Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"CatchBack Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://catchbackcards.mintlify.app/partner-api/v2/authentication\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://catchbackcards.mintlify.site/_mintlify/api/og/v2?division=Get+started\u0026amp;title=Authentication+and+keys\u0026amp;description=The+bearer+key%2C+the+nft%3Aorders+scope%2C+your+program%2C+and+how+to+rotate%2C+revoke+and+handle+a+key.\u0026amp;theme=779a40f3f67beacb233f5a4b\u0026amp;signature=d5ba2086037272a2ba38e09f043dee4044683ade2dfb46a6cea248ee52ce4309\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Authentication and keys - CatchBack Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://catchbackcards.mintlify.site/_mintlify/api/og/v2?division=Get+started\u0026amp;title=Authentication+and+keys\u0026amp;description=The+bearer+key%2C+the+nft%3Aorders+scope%2C+your+program%2C+and+how+to+rotate%2C+revoke+and+handle+a+key.\u0026amp;theme=779a40f3f67beacb233f5a4b\u0026amp;signature=d5ba2086037272a2ba38e09f043dee4044683ade2dfb46a6cea248ee52ce4309\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/catchbackcards/mlIgZutg782HIdAn/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"CatchBack Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#16A34A\">\u003clink data-mint-head rel=\"canonical\" href=\"https://catchbackcards.mintlify.app/partner-api/v2/authentication\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/partner-api/v2/authentication.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://catchbackcards.mintlify.app/#organization\",\"name\":\"CatchBack Documentation\",\"url\":\"https://catchbackcards.mintlify.app\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/catchbackcards/t6yI8GaEaBqQQEpE/logo/catchback_logo_dark.png?fit=max\u0026auto=format\u0026n=t6yI8GaEaBqQQEpE\u0026q=85\u0026s=c0a46c19893e31a50cd0f4716d47686b\"}},{\"@type\":\"WebSite\",\"@id\":\"https://catchbackcards.mintlify.app#website\",\"name\":\"CatchBack Documentation\",\"url\":\"https://catchbackcards.mintlify.app\",\"publisher\":{\"@id\":\"https://catchbackcards.mintlify.app/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication#webpage\",\"url\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication\",\"name\":\"Authentication and keys\",\"description\":\"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.\",\"dateModified\":\"2026-11-18T02:02:13.147Z\",\"isPartOf\":{\"@id\":\"https://catchbackcards.mintlify.app#website\"},\"breadcrumb\":{\"@id\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Get started\",\"item\":\"https://catchbackcards.mintlify.app/partner-api/v2/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Authentication and keys\",\"item\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication#article\",\"headline\":\"Authentication and keys\",\"name\":\"Authentication and keys\",\"description\":\"The bearer key, the nft:orders scope, your program, and how to rotate, revoke and handle a key.\",\"url\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication\",\"mainEntityOfPage\":{\"@id\":\"https://catchbackcards.mintlify.app/partner-api/v2/authentication#webpage\"},\"dateModified\":\"2026-11-18T02:02:13.147Z\",\"publisher\":{\"@id\":\"https://catchbackcards.mintlify.app/#organization\"},\"isPartOf\":{\"@id\":\"https://catchbackcards.mintlify.app#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"CatchBack Documentation\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"CatchBack Documentation\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/partner-api/v2/authentication.md","siteName":"CatchBack Documentation","nav":{"global":{"anchors":[{"anchor":"CatchBack Website","icon":"globe","href":"https://catchbackcards.com"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/about-catchback/overview"}]},{"tab":"Partner API","groups":[{"group":"Get started","pages":[{"title":"Partner API v2","sidebarTitle":"Overview","href":"/partner-api/v2/overview"},{"title":"MCP server","href":"/partner-api/v2/mcp"},{"title":"Sandbox","description":null,"href":"/partner-api/v2/quickstart"},{"title":"Authentication and keys","href":"/partner-api/v2/authentication"}]},{"group":"Concepts","pages":[{"title":"Orders and statuses","description":"The lifecycle of a wallet order, multi-pack orders and their units, and what each status means.","href":"/partner-api/v2/orders"},{"title":"Verify a pull","href":"/partner-api/v2/verify-a-pull"},{"title":"Odds","href":"/partner-api/v2/odds"},{"title":"Payments","href":"/partner-api/v2/payments"},{"title":"Sell-back","href":"/partner-api/v2/sell-back"},{"title":"Shipping","href":"/partner-api/v2/shipping"},{"title":"Webhooks","href":"/partner-api/v2/webhooks"},{"title":"Chains, tokens and metadata","href":"/partner-api/v2/chains-and-metadata"},{"title":"Idempotency","href":"/partner-api/v2/idempotency"},{"title":"Errors","href":"/partner-api/v2/errors"},{"title":"Limits and compliance","href":"/partner-api/v2/limits-and-compliance"}]},{"group":"Packs \u0026 orders","pages":[{"title":"List packs","api":"GET /api/partner/v2/catalog/packs","href":"/partner-api/v2/endpoints/list-packs"},{"title":"Get a pack's odds and pool","api":"GET /api/partner/v2/catalog/packs/pool","href":"/partner-api/v2/endpoints/get-pack-pool"},{"title":"Create an order","api":"POST /api/partner/v2/orders","href":"/partner-api/v2/endpoints/create-order"},{"title":"List orders","api":"GET /api/partner/v2/orders","href":"/partner-api/v2/endpoints/list-orders"},{"title":"Get an order","api":"GET /api/partner/v2/orders/{id}","href":"/partner-api/v2/endpoints/get-order"},{"title":"Verify an order's pull","api":"GET /api/partner/v2/orders/{id}/verification","href":"/partner-api/v2/endpoints/get-order-verification"}]},{"group":"Tokens \u0026 sell-back","pages":[{"title":"List a wallet's tokens","api":"GET /api/partner/v2/wallets/{address}/tokens","href":"/partner-api/v2/endpoints/list-wallet-tokens"},{"title":"Get a token","api":"GET /api/partner/v2/tokens/{tokenId}","href":"/partner-api/v2/endpoints/get-token"},{"title":"Quote a sell-back","api":"POST /api/partner/v2/tokens/{tokenId}/quote","href":"/partner-api/v2/endpoints/create-sellback-quote"},{"title":"List sell-back quotes","sidebarTitle":"List quotes","api":"GET /api/partner/v2/quotes","href":"/partner-api/v2/endpoints/list-quotes"},{"title":"Get a quote","api":"GET /api/partner/v2/quotes/{quoteId}","href":"/partner-api/v2/endpoints/get-quote"},{"title":"Token metadata","api":"GET /api/partner-nfts/metadata/{chainId}/{tokenId}","href":"/partner-api/v2/endpoints/get-token-metadata"}]},{"group":"Shipments","pages":[{"title":"Estimate a shipment","api":"POST /api/partner/v2/shipments/estimate","href":"/partner-api/v2/endpoints/estimate-shipment"},{"title":"Create a shipment","api":"POST /api/partner/v2/shipments","href":"/partner-api/v2/endpoints/create-shipment"},{"title":"Estimate a one-token shipment","api":"POST /api/partner/v2/tokens/{tokenId}/shipment/estimate","href":"/partner-api/v2/endpoints/estimate-token-shipment"},{"title":"Create a one-token shipment","api":"POST /api/partner/v2/tokens/{tokenId}/shipment","href":"/partner-api/v2/endpoints/create-token-shipment"},{"title":"List shipments","api":"GET /api/partner/v2/shipments","href":"/partner-api/v2/endpoints/list-shipments"},{"title":"Get a shipment","api":"GET /api/partner/v2/shipments/{id}","href":"/partner-api/v2/endpoints/get-shipment"},{"title":"Renew a shipment","api":"POST /api/partner/v2/shipments/{id}/renew","href":"/partner-api/v2/endpoints/renew-shipment"}]},{"group":"Webhook endpoints","pages":[{"title":"Register a webhook","api":"POST /api/partner/v2/webhooks","href":"/partner-api/v2/endpoints/register-webhook"},{"title":"Get your webhook","api":"GET /api/partner/v2/webhooks","href":"/partner-api/v2/endpoints/list-webhooks"},{"title":"Delete a webhook","api":"DELETE /api/partner/v2/webhooks/{id}","href":"/partner-api/v2/endpoints/delete-webhook"},{"title":"Test a webhook","api":"POST /api/partner/v2/webhooks/{id}/test","href":"/partner-api/v2/endpoints/test-webhook"}]},{"group":"Keys \u0026 revenue","pages":[{"title":"Get your key","api":"GET /api/partner/v2/keys","href":"/partner-api/v2/endpoints/get-key"},{"title":"Rotate your key","api":"POST /api/partner/v2/keys/rotate","href":"/partner-api/v2/endpoints/rotate-key"},{"title":"Revoke the previous key","api":"POST /api/partner/v2/keys/revoke-previous","href":"/partner-api/v2/endpoints/revoke-previous-key"},{"title":"Get your revenue statement","api":"GET /api/partner/v2/revenue","href":"/partner-api/v2/endpoints/get-revenue"}]},{"group":"Sandbox","pages":[{"title":"Simulate a payment","api":"POST /api/partner/v2/sandbox/payments/{intentId}","href":"/partner-api/v2/endpoints/sandbox-pay"},{"title":"Run the background work","api":"POST /api/partner/v2/sandbox/tick","href":"/partner-api/v2/endpoints/sandbox-tick"},{"title":"Mark a shipment shipped or delivered","sidebarTitle":"Simulate shipping","api":"POST /api/partner/v2/sandbox/shipments/{id}","href":"/partner-api/v2/endpoints/sandbox-ship"}]},{"group":"Going live","pages":[{"title":"Go-live checklist","href":"/partner-api/v2/go-live-checklist"},{"title":"Changelog","href":"/partner-api/v2/changelog"}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/packs/list-packs"}]}]},"basePath":"","title":"Authentication and keys - CatchBack Documentation","deploymentId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","buildId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","dynamics":[],"chunks":[]}