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 and tasks |
projects:write | Create, update, and delete projects and tasks |
clients:read | Read clients |
clients:write | Create, update, and delete clients |
tags:read | Read tags |
tags:write | Create, update, and delete tags |
work_sessions:read | Read AI work sessions |
work_sessions:write | Log AI work sessions |
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+work_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.