API Keys

API keys authenticate automated systems (CLI, CI/CD pipelines, scripts) with your Cofactor 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:

cofactor test --remote --token cnry_your_api_key

Or set it as an environment variable:

export CANARY_API_TOKEN=cnry_your_api_key
cofactor 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 your tests for a GitHub Actions example, or Running your tests 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.

06Sandbox permissions

The Sandboxes permission (the sandbox scope) covers Sandboxes v2: pushing application images, claiming, showing and destroying sandboxes, and running their actions. It appears in the scoped-key picker only when Sandboxes v2 is enabled for your organization.

Every CLI command that takes --application also needs property:read: the CLI lists your applications to resolve it, even when you pass an id.

A minimal CI key

Expose the key to the job as COFACTOR_API_TOKEN (or CANARY_API_TOKEN). See Sandboxes from a pushed image → Run it from CI.

Because sandbox:read returns working logins for every sandbox in your organization, store the key like any other secret and grant it only to jobs that need it. Prefer listing actions over sandbox:*: a wildcard also grants any sandbox action added later, without asking.

07Revoking 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

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

09Token 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 cofactor login)

The first value found is used.

10Related

• Running your tests
• Running your tests
• CLI reference
• Authentication overview
• Sandboxes v2