{
  "object": "doc",
  "title": "How does Cartroute API authentication work?",
  "description": "Bearer API keys: format, storage, rotation and scopes.",
  "section": "Getting started",
  "url": "https://cart-route.com/docs/authentication",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/quickstart",
  "next": "https://cart-route.com/docs/credits",
  "text": "Every metered and account endpoint needs an API key sent as `Authorization: Bearer cr_live_...` (or as an `X-API-Key` header). Keys are created in the dashboard or by `POST /api/v1/accounts`, are shown once, and are never accepted in the URL.\n\n## How do I send the key?\n\n```\ncurl \"https://cart-route.com/api/v1/account\" -H \"Authorization: Bearer $CARTROUTE_API_KEY\"\n\n# equivalent\ncurl \"https://cart-route.com/api/v1/account\" -H \"X-API-Key: $CARTROUTE_API_KEY\"\n```\n\nA key in a query string is ignored on purpose: URLs are written to proxy, browser and server logs, so a key placed there should be treated as leaked.\n\n## What does a key look like?\n\n`cr_live_` followed by 40 URL-safe characters. The dashboard shows only the first 16 characters afterwards (for example `cr_live_8fJ2kQ1a…`) so you can tell keys apart.\n\n## How are keys stored?\n\nCartroute keeps only a SHA-256 hash of each key. A lost key cannot be recovered or displayed again; revoke it and create a new one.\n\n## How many keys can an account have?\n\nTen active keys. Use one per environment or per agent so a leak can be revoked without downtime elsewhere, and so the dashboard shows usage per key.\n\n## How do I rotate a key?\n\n- Create a new key in the [dashboard](https://cart-route.com/dashboard).\n\n- Deploy it to the agent or service.\n\n- Watch the old key's Last used time stop moving.\n\n- Revoke the old key. Requests using it immediately return `401 unauthorized`.\n\n## What does an authentication failure return?\n\n`401` with `code: \"unauthorized\"` when the key is missing, malformed or revoked, and `403` with `code: \"account_suspended\"` when the account has been suspended. Neither is charged. See [errors](https://cart-route.com/docs/errors).\n\n## Which endpoints need no key?\n\n`GET /api/v1`, `/retailers`, `/categories`, `POST /accounts`, the MCP discovery methods (`initialize`, `tools/list`, `resources/*`, `prompts/*`) and every public web page, including its [JSON form](https://cart-route.com/docs/pages-as-json).\n\n## Is CORS enabled?\n\nYes, for every origin. The API authenticates with keys, never cookies, so cross-origin calls carry no ambient credentials. Do not ship a key in public browser code: anyone can read it. Call the API from your server or agent runtime."
}