API
Permissions and plans
API tokens inherit the role of the member who created them. Learn what each role can do over the API and which plan is required.
The API enforces the same permissions as the app. A token has no special powers — it acts as the member who created it, on a workspace that must have API access.
Plan requirement
API access is the apiAccess entitlement, included on Studio and Agency. On the Free plan
(or if a paid plan lapses), every API request returns:
{ "error": { "code": "forbidden_plan", "message": "...", "requiredPlan": "studio", "feature": "apiAccess" } }with HTTP 402. See Plans & limits.
Roles over the API
A token inherits its creator's role. The effective access:
| Resource | Owner / Admin | Manager | Member |
|---|---|---|---|
| Clients | Full CRUD | Full CRUD | No access |
| Projects | Full CRUD | Full CRUD | Read projects they're on |
| Tasks | Full CRUD | Full CRUD | Read + edit tasks assigned to them |
| Time entries | Full CRUD (any member) | Full CRUD (any member) | Their own un-invoiced entries |
| Expenses | Full CRUD | Full CRUD | No access |
| Invoices | Read | Read | No access |
| Members / Organization | Read | Read | Read only their own member record |
Members are money-blind over the API too. A Member token never receives rates or amounts, can't reach invoices, expenses, or clients, and only sees projects it's been added to — exactly like the app. See Money-blindness.
Errors you'll see
402 forbidden_plan— the workspace lacks API access (upgrade to Studio).403 forbidden_scope— the role can't perform this action (e.g. a Member trying to create an expense).409 conflict— the action is blocked by state (e.g. editing an invoiced, locked time entry, or deleting a client with active projects).
Tips
- For an integration that should be able to do everything, mint the token as an Owner or Admin.
- For a narrowly-scoped automation (e.g. a contractor's time logger), mint it as a Member so it can only touch that person's own time on their projects.
Was this page helpful?