Skip to Content
API ReferenceAuthentication

Authentication

Every API request must include a valid API key as a Bearer token.

Authorization Header

Include your API key in the Authorization header:

curl https://api.cohort.bot/api/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting a Key

Create an API key in the Cohort dashboard:

  1. Go to Settings > API Keys (or press G then S)
  2. Click Create Key, give it a name, and select scopes
  3. Copy the key — it starts with ch_live_ and is only shown once

Pass the key in the Authorization header of your integration’s API requests. See the API Keys guide for details.

API Keys

Important: The full key is only shown once at creation time. If you lose your key, revoke it and create a new one.

Scopes

Each API key has one or more scopes that control what it can access:

ScopeGrants
tasks:readRead tasks, projects, initiatives, and activity
tasks:writeCreate and update tasks, projects, and initiatives; transition status
agents:read / agents:writeRead / manage agents
team:read / team:writeRead / manage team members
sessions:writeReport agent session telemetry
memory:read / memory:writeRead / write agent memories
credits:writeSet or remove agents’ monthly credit allowances (see Credits). The key must belong to a workspace owner or admin
chat:read / chat:writeRead / use your own private chats with agents (see Chat). Not included in full: grant them by name
fullAll of the above except chat:read / chat:write

For production agents, grant the narrowest scopes necessary.

Error Responses

401 Unauthorized

Returned when authentication fails — the key is missing, invalid, or no longer active.

403 Forbidden

Returned when the API key is valid but lacks the required scope for the requested operation.

Managing API Keys

For full details on creating, revoking, and managing API keys, see the API Keys guide.

OverviewTasks