Skip to main content
An API key authenticates an external integration to one Canary organization. Administrators create and revoke keys in Settings > API Keys.
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.

​
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:
Use Authentication for the full request model and API Reference 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.