Authentication

Every request carries your API key in the X-API-Key header. How to keep it safe, rotate it, and what the API answers when a key is missing, wrong or ended.

Send the Key in a Header

Authenticate every request with your key in the X-API-Key header. It is the only credential the public API accepts: there are no query-string keys, cookies or bearer tokens. The same header authenticates the WebSocket handshake.

curl -s "https://api.cantoncap.cc/v1/global/metrics/latest" \
  -H "X-API-Key: $CANTONCAP_API_KEY"

Each key belongs to one plan, and the plan decides how many requests a minute it may make, how far back it may read and how large a page it may ask for. See Plans and limits.

Keep the Key Secret

Call the API from a server. Anything shipped to a browser or a mobile app can be read by its users. Put a small endpoint of your own in front of the API and cache what it returns.
Keep it out of source control. Load it from an environment variable or a secret manager. Keys issued on cantoncap.cc begin with ccsk_, which makes them easy to find with a secret scanner.
Keep it out of logs and URLs. The API never takes a key in the query string; do not put it in one of your own.
One key per system. If you run several services, separate keys let you replace one without touching the others. Write to api@cantoncap.cc for more than one.

Responses to authenticated requests carry Cache-Control: private, no-cache and Vary: X-API-Key where they can be cached at all, so a shared cache does not hand one key's answer to another. If you put a cache in front of the API, keep it private to your service.

Replace (Rotate) a Key

Open Account, API keys and choose Replace key. The new key has the same plan and end date.
The new key goes live with the next update, usually within one business day. We email you when it answers.
Deploy the new key. The old one keeps working for seven days after the new one is live, so there is no gap.

Leaked Key

If a key has leaked, replace it and write to api@cantoncap.cc so we can end the old one at once instead of after the seven days.

When a Key Is Refused

Situation	Status	error.code	What to do
No X-API-Key header, or a key the API does not know (including a key ended more than 30 days ago)	401	`unauthenticated`	Check the header name and that the full key was copied. Keys are shown again under Account, API keys.
The key exists but its plan is not active: it expired, was suspended, or has not started yet	403	`forbidden`	Renew the plan or check its state on the account page. The message is The API key does not resolve to an active plan.
The request asks for more than the plan allows (page size or history depth)	403	`quota_exceeded`	Lower limit or shorten the range. See Plans and limits.
The key used up this minute's requests	429	`rate_limited`	Wait for Retry-After seconds. See Rate limits.

A subscription key stays active for three days past the paid period so a renewal can land. After a key ends, it answers 403 forbidden for 30 days, so you can tell an ended key from a mistyped one, and 401 unauthenticated after that.

JSON

{
  "status": {
    "timestamp": "2026-10-11T14:00:00.000Z",
    "elapsed_ms": 1,
    "error_code": 1002,
    "error_message": "The API key does not resolve to an active plan",
    "request_id": "req_7Hk2pQ9xLm"
  },
  "error": {
    "code": "forbidden",
    "message": "The API key does not resolve to an active plan",
    "retryable": false
  }
}

What a Key Can See

Every key reads the same approved public data. A key never unlocks private records on a public endpoint, and an unpublished record answers 404 without saying whether it exists. The plans differ in volume and depth, not in which endpoints or fields they reach.