Cano Analytics API Authentication: Keys, Scopes, and Errors

Every request to the Cano Analytics API must include an API key passed as a Bearer token in the Authorization header. There are no session cookies or OAuth flows for server-to-server calls — your API key is the single credential that identifies your workspace and determines what actions you are allowed to perform.

Generating an API Key

Open API Keys settings

Create a new key

Click Generate Key. Give the key a descriptive name (e.g., production-backend or data-pipeline-read) so you can identify it later.

Select a scope

Choose the minimum scope your integration needs. See Key Scopes below for a description of each option.

Copy and store the key securely

The key is shown only once immediately after creation. Copy it and store it in a secrets manager or environment variable — you cannot retrieve it again from the dashboard.

Key Scopes

Scopes follow the principle of least privilege. Grant only the permissions your integration actually needs.

Scope	What it allows
write	Track events (`POST /v1/events`) and identify users (`POST /v1/identify`)
read	Query dashboards, reports, and user data
admin	Manage workspace settings, team members, and billing

A single key can hold multiple scopes. For example, a backend service that both ingests events and reads dashboard data needs both write and read.

Passing Your Key in Requests

Add the Authorization header to every API request using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

Here is a complete example that lists recent events using a live production key:

curl https://api.canoanalytics.io/v1/events \
  -H "Authorization: Bearer cano_live_sk_1234567890abcdef"

Key Naming Conventions

Cano keys are prefixed to indicate their environment at a glance:

Prefix	Environment	Use for
`cano_live_sk_...`	Production	Real user data and live workflows
`cano_test_sk_...`	Test / Sandbox	Development, CI, and staging environments

Test keys behave identically to live keys but their data is isolated and never mixed with production records. Use test keys in any non-production environment.

Authentication Errors

If your request is rejected due to an authentication or authorization problem, the API returns one of the following errors:

HTTP Status	Error Code	Meaning
`401`	`unauthorized`	The `Authorization` header is missing or the API key is invalid
`403`	`forbidden`	The key is valid but does not have the required scope for this action
`429`	`rate_limited`	Your key has exceeded the allowed request rate — back off and retry

All error responses follow the standard error shape:

Error Response

{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have write scope."
  }
}

Never embed API keys in client-side JavaScript, mobile app binaries, or public repositories. Anyone who obtains your key can send requests on behalf of your workspace. Use environment variables or a secrets manager on the server side, and use the Cano JavaScript SDK’s write-only public key for browser-based event tracking.

If a key is ever exposed or compromised, immediately go to Settings → API Keys, find the affected key, and click Revoke. Revocation takes effect within seconds. Then generate a replacement key and update your integration.

Overview

Endpoints

SDKs

Cano Analytics API Authentication: Keys, Scopes, and Errors

Generating an API Key

Key Scopes

Passing Your Key in Requests

Key Naming Conventions

Authentication Errors

​Generating an API Key

​Key Scopes

​Passing Your Key in Requests

​Key Naming Conventions

​Authentication Errors

Generating an API Key

Key Scopes

Passing Your Key in Requests

Key Naming Conventions

Authentication Errors