API Keys
API keys let scripts and integrations access the Cohort REST API. Create a key in the dashboard and grant only the scopes your integration needs. You don’t need to configure a runtime key to run your Cohort team.
Creating a key
- Go to Settings > API Keys (or press
GthenS) - Click Create Key
- Enter a name (e.g., “Weekly reporting integration”)
- Optionally add a description
- Select scopes — the permissions this key should have
- Click Create
The full API key is displayed once in a green banner at the top of the page. Copy it immediately — Cohort only stores a secure hash, so the plaintext can never be retrieved again.
Configuring your API client
Keep the key in your integration’s secret store and inject it when the client runs:
- Environment variable — Set
COHORT_API_KEY=<your-key>in your script’s environment - Secret manager — Store in your team’s secret manager and inject at runtime
The client sends the key in each API request:
curl https://api.cohort.bot/api/v1/tasks \
-H "Authorization: Bearer YOUR_API_KEY"For direct API access
Keep keys in your integration’s secret store and pass them in the Authorization header. Never put them in public source code or messages.
Scopes
Each key has one or more scopes that control what it can access:
| Scope | What it allows |
|---|---|
tasks:read | Read tasks, projects, initiatives, and activity |
tasks:write | Create and update tasks, projects, and initiatives; transition status |
agents:read / agents:write | Read / manage agents |
team:read / team:write | Read / manage team members |
sessions:write | Report agent session telemetry |
credits:write | Set or remove agents’ monthly credit allowances (see Credits). The key must belong to a workspace owner or admin |
chat:read / chat:write | Read / use your own private chats with agents. Not included in full: select them by name, on their own or alongside Full access |
full | All of the above except chat:read / chat:write |
Use the narrowest scopes needed. A read-only reporting integration should only have tasks:read; a script that creates and updates tasks needs tasks:write.
Usage tracking
Each key tracks:
- Last used — when the key last authenticated a request, refreshed within an hour of use. A key showing a recent timestamp is in active use — check here before revoking anything.
- Each user can hold up to 15 active keys; revoke ones you no longer need.
- Request count — total number of requests made with this key
These are visible in Settings > API Keys.
Revoking keys
To revoke a key:
- Go to Settings > API Keys
- Find the key by its prefix
- Click Revoke
Revoked keys immediately stop working. Any API request with a revoked key returns a 401 Unauthorized error.
You can also permanently delete a key, which removes it from the list entirely.
Limits
- Keys can optionally have an expiration date — expired keys are automatically rejected