API Keys

Create and manage API keys for CLI and CI/CD authentication.

API keys authenticate automated systems (CLI, CI/CD pipelines, scripts) with your Canary organization. Unlike user sessions, they don't expire on browser close and are designed for non-interactive use.

Key format

API keys use the prefix cnry_ followed by a random string. The full key is shown only once at creation time. After that, only the prefix is visible in the UI.

Who can create keys

Only organization admins can create and revoke API keys. Members can view existing keys but cannot create or delete them.

Creating a key

  1. Go to Settings > API Keys
  2. Click Create Key
  3. Enter a descriptive name (e.g., "GitHub Actions", "Nightly Smoke Tests", "Staging Deploy Gate")
  4. Copy the key immediately -- it will not be shown again

Using a key

With the CLI

Pass the key directly:

canary test --remote --token cnry_your_api_key

Or set it as an environment variable:

export CANARY_API_TOKEN=cnry_your_api_key
canary test --remote --tag smoke

In CI/CD

Store the key as a secret in your CI platform and expose it as CANARY_API_TOKEN. See Running tests with the CLI for a GitHub Actions example, or CI/CD Integration for other platforms.

With the API directly

curl -X POST https://api.trycanary.ai/workflows/test-runs \
  -H "Authorization: Bearer cnry_your_api_key"

Revoking a key

  1. Go to Settings > API Keys
  2. Click the delete icon next to the key you want to revoke
  3. The key is immediately invalidated -- any pipeline using it will start failing

Security best practices

  • Never commit keys to source control. Use your CI platform's secrets management.
  • Create separate keys per pipeline so you can revoke one without breaking others.
  • Use descriptive names so you know which key belongs to which system.
  • Rotate keys periodically. Create a new key, update your pipelines, then revoke the old one.
  • Revoke unused keys. If a pipeline is decommissioned, revoke its key.

Token resolution order

When the CLI needs a token, it checks in this order:

  1. --token command-line flag
  2. CANARY_API_TOKEN environment variable
  3. Stored login token at ~/.config/canary-cli/auth.json (from canary login)

The first value found is used.