Canonical Docs
Sign up

Authentication

Every API request authenticates with an API key passed in the x-api-key header.

API keys

Create and revoke keys in Settings → API Keys. Keys start with sk_; the full value is shown once at creation — after that only the prefix (e.g. sk_abc1234) is displayed, so copy it immediately. Lost keys can't be recovered, only replaced: create a new key, switch your integration over, then revoke the old one.

The API reference can mint a dedicated “Docs playground” key with one click, so you can try endpoints without leaving the docs.

Using your key

curl "https://trycanonical.ai/api/v1/search?q=fintech+startups" \
  -H "x-api-key: $CANONICAL_API_KEY"

Keys are organization-scoped: usage, credits, and rate limits are shared across your workspace. All requests must use HTTPS.

Authentication errors

A missing or invalid key returns 401:

{
  "detail": "API key required. Include x-api-key header."
}

A well-formed but revoked or unknown key gets the same 401 — the API doesn't distinguish, so a sudden wave of 401s after a key rotation usually means a service is still holding the old key.

Keeping keys safe

  • Call the API from your backend only — a key shipped to a browser or mobile app is public.
  • Store keys in environment variables or a secrets manager, never in source control.
  • Use separate keys per environment/service so one can be revoked without breaking the others.
  • Revoke anything you suspect leaked in Settings → API Keys — revocation is immediate.