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

# API keys

> Create scoped test or live credentials for Canary public API integrations.

An API key authenticates an external integration to one Canary organization. Administrators create and revoke keys in **Settings > API Keys**.

<Warning>
  Test and live identify credential and rate-limit tiers. Both act on the organization authorized by the key according to their scopes. Use a dedicated non-production organization when testing data-changing integrations.
</Warning>

## Create a key

1. Open **Settings > API Keys**.
2. Select **Create API Key**.
3. Enter a name that identifies the integration and environment.
4. Choose **Test** or **Live**.
5. Select only the required read and write scopes.
6. Create the key.
7. Copy the complete secret immediately and store it in a secret manager.

Canary displays the full secret once. The product stores a one-way hash and later shows only the key prefix, creation time, environment, and last-used state.

## Available scope families

Read and write scopes are available for:

* Meters and readings
* Work orders
* Work requests and their attachments
* Work Request Portals
* Assets
* Locations
* Parts
* Scannable identifiers
* Custom fields

Each endpoint documents its required scope. Write requests require the corresponding write scope.

## Authenticate a request

Send the key as a Bearer token:

```bash theme={"theme":"github-light"}
curl --fail-with-body https://api.oncanary.com/v1/assets \
  -H "Authorization: Bearer $CANARY_API_KEY"
```

Use [Authentication](/authentication) for the full request model and [API Reference](/api-reference/overview) for endpoint scopes.

## Rotate or revoke a key

1. Create a replacement with the same required scopes.
2. Update the integration secret and verify a request.
3. Return to **API Keys** and revoke the old key.

Revocation takes effect for subsequent authentication and is permanent. Create a new key if access is needed again.

## Security practices

* Use a separate key for each integration and deployment context.
* Keep keys out of browsers, mobile bundles, source control, logs, and screenshots.
* Grant write scopes only where the integration writes that resource.
* Review **Last used** and revoke unused or exposed credentials.

## Related pages

* [API errors](/help/troubleshooting/api-errors)
* [Authentication](/authentication)
* [Rate limits](/guides/rate-limits)