Scopes & Permissions
Understand API key scopes and what each permission level allows.
API keys can be created with specific scopes to limit what they can access. This follows the principle of least privilege — only grant the permissions your integration needs.
Available scopes
| Scope | Description |
|---|---|
entries:read | Read time entries |
entries:write | Create, update, and delete time entries |
projects:read | Read projects |
projects:write | Create, update, and delete projects |
tasks:read | Read workstreams |
tasks:write | Create, update, and delete workstreams |
clients:read | Read clients |
clients:write | Create, update, and delete clients |
invoices:read | Read invoices |
invoices:write | Create, update, and delete invoices |
tags:read | Read tags |
tags:write | Create, update, and delete tags |
agent_sessions:read | Read agent sessions |
agent_sessions:write | Log and update agent sessions |
ai_attributions:read | Read AI attributions |
ai_attributions:write | Create, update, and delete AI attributions |
ai_attributions:manage | Review and approve AI attributions |
ai_reporters:read | Read AI reporters |
ai_reporters:write | Create, update, and delete AI reporters |
external_id_mappings:read | Read external ID mappings |
external_id_mappings:write | Create, update, and delete external ID mappings |
skills:read | Read skills |
skills:write | Create, update, and delete skills |
members:read | Read workspace members |
members:write | Invite, update, and remove workspace members |
invitations:read | Read pending invitations |
invitations:write | Send and revoke invitations |
Workstreams are tasks in the API for historical reasons — the scope is tasks:*
but the product calls them workstreams.
Write implies read: a key with entries:write can also perform entries:read.
Scope combinations
When creating an API key, you can select any combination of scopes. Common patterns:
- Read-only integration — Select all
*:readscopes for dashboards and reporting. - Time tracking bot —
entries:read+entries:write+projects:read. - AI agent —
entries:write+projects:read+agent_sessions:writefor logging work.
Error handling
If your API key lacks a required scope, the API returns 403 Forbidden with a message indicating which scope is needed.