Guides
Scopes & permissions
A scope is the whole of a key's authority. A key is not a person: it holds no job title and inherits nothing.
Read and manage
Scopes come in pairs. .read lets you look; .manage lets you change. Asking for a .manage scope also grants the matching .read, tick tasks.manage and the key is created holding tasks.manage and tasks.read.
Ask for the least you need
Scopes are fixed when the key is made. If your integration only files tasks, ask for tasks.manage and nothing else. A leaked key is then worth almost nothing, and the customer can see exactly what you can touch.
What happens to a request
The middle gate is the one integrators forget. An organisation can have a whole product module switched off, and then no key of theirs reaches it regardless of scopes. That is a plan and configuration fact, not a permissions mistake: the fix is in the organisation's subscription, not in your code.
A refusal names what it wanted
Scope failures are machine-readable, so your client can log which permission to ask the customer for rather than a generic “forbidden”:
{
"success": false,
"error": "This key does not have the \"clients.read\" scope.",
"code": "scope_required",
"requiredScope": "clients.read",
"version": "v1"
}A 403 with no requiredScope is the module gate, not the scope gate. Treat the two differently: one is fixed by issuing a new key, the other by the customer changing plan.
Every scope
| Scope | Grants |
|---|---|
| organisation.read | The organisation record. |
| projects.read | Projects, milestones, risks and issues. |
| projects.manage | Create and change projects and milestones. |
| tasks.read | Tasks and their comments. |
| tasks.manage | Create, change, delete and comment on tasks. |
| calendar.read | Events and repeating series. |
| calendar.manage | Add, change and cancel events. |
| clients.read | Clients. |
| clients.manage | Create and change clients. |
| personnel.read | People, groups, certificates and compliance. |
| personnel.manage | Add and change people. |
| documents.read | Documents and download URLs. |
| documents.manage | Upload and change documents. |
| financials.read | Financial entries and totals. |
| financials.manage | Add financial entries. |
| assets.read | Assets and allocations. |
| assets.manage | Change assets and allocations. |
| webhooks.manage | Register and manage webhook endpoints. |