API Keys
Create and manage scoped API keys for authenticating with the Koalr public REST API.
Overview
API keys let you authenticate programmatic access to the Koalr REST API. Each key is scoped to specific permissions so you can grant the minimum access required for a given integration or pipeline.
Navigate to Settings > API Keys to manage your keys.
Creating a key
- Click + New Key.
- Enter a descriptive name (e.g., "CI/CD pipeline" or "BI export").
- Select the permissions the key should have. By default all scopes are selected; deselect any you do not need.
- Click Create Key.
- Copy the key immediately -- it is shown only once and cannot be retrieved later.
Available scopes
Each scope grants read access to a specific area of the API unless otherwise noted.
| Scope | Description |
|---|---|
read:dora | Deployment frequency, lead time, MTTR, CFR |
read:deployments | List deployment events |
read:prs | List and filter pull requests |
read:incidents | List incident records |
read:teams | List teams and membership counts |
read:flow | Cycle time, throughput, WIP |
read:review | Review bottleneck, tone, queue health |
read:copilot | GitHub Copilot usage and adoption metrics |
read:value-stream | Flow efficiency, lead time, stage breakdown |
read:forecasting | Monte Carlo delivery and backlog forecasts |
read:custom-metrics | Run saved custom metric queries |
write:custom-metrics | Create and update custom metrics |
If all scopes are selected at creation time, the key is stored with a wildcard (*) scope representing full access.
Key table
The API Keys page shows a table of all active keys with:
- Name -- the label you assigned at creation
- Key -- a truncated prefix for identification (the full key is never stored)
- Permissions -- the scopes assigned to the key, or "Full access" for wildcard keys
- Created -- the date the key was generated
- Last Used -- the last date the key was used to authenticate a request, or a dash if never used
Revoking a key
Click Revoke next to any key to permanently disable it. Revocation is immediate and cannot be undone. Any request using a revoked key will receive a 401 Unauthorized response.
Security considerations
- Store keys in environment variables or a secrets manager. Never commit them to source control.
- Use the narrowest scope set that meets your needs.
- Rotate keys periodically by creating a new key, updating your integration, and then revoking the old key.
- All key creation and revocation events are recorded in the Audit Log.
API reference
See the full API Reference for endpoint documentation. Pass the key in the Authorization header:
Authorization: Bearer koalr_sk_...