API Keys

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.

01Key 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.

02Who can create keys

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

03Creating a key

1. Go to Settings > API Keys
2. Click Create Key
3. Enter a descriptive name (for example, GitHub Actions, Nightly Smoke Tests, or Staging Deploy Gate)
4. Choose the key type:
   • Full access for unrestricted access
   • Scoped to allow only specific actions
5. If you create a scoped key, select the permissions you want to allow
6. Copy the key immediately -- it will not be shown again

Use scoped keys for CI/CD jobs, scripts, and other automation that only needs a limited set of actions. Use full-access keys only when the workflow genuinely requires unrestricted access.

04Using 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. Prefer scoped keys for each pipeline so every job gets only the permissions it needs. If a job starts failing after you switch from a full-access key to a scoped key, review the key's allowed permissions and update the scope or use a separate key for that workflow.

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"

Use a key whose permissions match the API actions your integration needs. If you automate multiple tasks, create separate scoped keys instead of sharing one broad key across unrelated systems.

05Key types and permissions

The Settings > API Keys list shows each key's effective permission model so you can understand access at a glance. Newly created keys appear at the top of the list, so you can find and verify recent changes quickly.

If you see Legacy in the list, plan to rotate that key. Create a replacement key, update the automation that uses it, confirm the workflow succeeds, and then revoke the old key.

06Revoking a key

1. Go to Settings > API Keys
2. Review the list, which is sorted with the newest keys first, to find the key you want to revoke
3. Click the delete icon next to the key you want to revoke
4. The key is immediately invalidated -- any pipeline using it will start failing

07Security 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 scoped keys when possible so each automation flow gets only the access it needs.
• 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.
• Replace legacy keys over time. Move long-lived automation to scoped or full-access keys that reflect current access controls.
• Revoke unused keys. If a pipeline is decommissioned, revoke its key.

08Token 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.

09Related

• Running tests with the CLI
• CI/CD Integration
• CLI reference
• Authentication overview