{
  "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": "Search, product, price-history and coupon calls work without a key for 10 calls a day per client IP, so an agent can try Cartroute with no setup; keyless results come from recent searches and the products re-checked daily. For fresh retailer lookups, more calls, and for the account endpoints, send an API key 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\r\n\r\n\n## How do I send the key?\n\r\n\n```\ncurl \"https://cart-route.com/api/v1/account\" -H \"Authorization: Bearer $CARTROUTE_API_KEY\"\r\n\r\n# equivalent\r\ncurl \"https://cart-route.com/api/v1/account\" -H \"X-API-Key: $CARTROUTE_API_KEY\"\n```\n\r\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\r\n\r\n\n## What does a key look like?\n\r\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\r\n\r\n\n## How are keys stored?\n\r\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\r\n\r\n\n## How many keys can an account have?\n\r\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\r\n\r\n\n## How do I rotate a key?\n\r\n\r\n\n- Create a new key in the [dashboard](https://cart-route.com/dashboard).\r\n\n- Deploy it to the agent or service.\r\n\n- Watch the old key's Last used time stop moving.\r\n\n- Revoke the old key. Requests using it immediately return `401 unauthorized`.\r\n\n\r\n\r\n\n## What does an authentication failure return?\n\r\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\r\n\r\n\n## Which endpoints need no key?\n\r\nKeyless within the daily allowance: `/search`, `/products/{id}`, `/products/{id}/price-history`, `/coupons` and the matching MCP tools (the response carries an `anonymous` block with the calls left; over the limit you get [`anonymous_limit_reached`](https://cart-route.com/docs/errors#anonymous_limit_reached)). Always free: `GET /api/v1`, `/tools`, `/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\r\n\r\n\n## Is CORS enabled?\n\r\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."
}