API Keys
API keys (Pro) provide bearer authentication for automation and integrations.
When to use API keys
Section titled “When to use API keys”API keys are designed for programmatic access:
- CI/CD suite triggers and gating
- external automation scripts
- internal tooling that reads run results
Do not use personal session tokens in CI pipelines.
Create a key in UI
Section titled “Create a key in UI”Creating a key takes a few seconds in the dashboard.
- Open API Keys (
/settings/api-keys). - Click Create API Key .
- Name the key by workload (
ci-main-deploy,nightly-regression). - Select scopes.
- Copy the secret once and store securely.
Scope strategy
Section titled “Scope strategy”Give each key only the permissions it needs. This limits blast radius if a key is compromised.
- read-only keys for reporting jobs
- run-trigger keys for CI gates
- separate keys per environment/repo
Key rotation process
Section titled “Key rotation process”Rotate keys periodically and immediately if you suspect exposure.
Use the Regenerate action to issue a new token for the same key, preserving its name and scopes. The old token is invalidated immediately.
- Regenerate the key (dashboard or API).
- Update the secret in CI/system.
- Run a test workflow to confirm.
Security checklist
Section titled “Security checklist”Quick audit checklist for your API key hygiene.
- never commit keys to Git
- store keys in secret manager only
- rotate regularly
- revoke keys on team member offboarding or integration decommission
Scope examples
Section titled “Scope examples”runs:writeandruns:read: CI gate job triggering and verdict checkssuites:read: pipeline job validating suite existence before trigger- read-only monitoring integration:
runs:readonly
Failure handling
Section titled “Failure handling”If your automation suddenly gets auth errors, here is what to check.
- verify key is active and not revoked
- check required scopes for called endpoint
- confirm key belongs to correct tenant/workspace
- rotate key if secret leakage is suspected