> ## Documentation Index
> Fetch the complete documentation index at: https://canopy.wnstn.space/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cano Analytics API Authentication: Keys, Scopes, and Errors

> Learn how to create and scope Cano Analytics API keys, add Bearer tokens to requests, and handle authentication and authorization 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

<Steps>
  <Step title="Open API Keys settings">
    Log in to [app.canoanalytics.io](https://app.canoanalytics.io) and navigate to **Settings → API Keys**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Select a scope">
    Choose the minimum scope your integration needs. See [Key Scopes](#key-scopes) below for a description of each option.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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                      |

<Note>
  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`.
</Note>

## 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:

```bash theme={null}
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:

```json Error Response theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have write scope."
  }
}
```

<Warning>
  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.
</Warning>

<Tip>
  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.
</Tip>