Access control
Two things decide whether a call succeeds: the role of the key and the plan of your business.
Roles
When you create a key you assign it a role, exactly as you would for a staff member:
| Role | What the key can do |
|---|---|
| Admin | Everything in this API. |
| Staff | The built-in Staff permissions: create/edit sales and purchase documents and payments, create/edit contacts, read items and bank accounts. |
| Accountant | The built-in Accountant permissions: read sales and purchase documents and payments, write journal entries and opening balances, read contacts/items/accounts, and read all reports. |
| Custom role | Any role you created under Settings > Custom Roles. The key is limited to exactly what that role is allowed to do. |
Prefer a custom role scoped to exactly what the integration needs, and reserve Admin for integrations that genuinely need broad access.
Each endpoint below lists the permission it needs. Permissions have three levels, each including the one before it:
| Level | Meaning |
|---|---|
| Read | View and list records. |
| Write | Read, plus create and update. |
| Full | Read and write, plus delete. |
Where an endpoint says any role, every valid key can call it regardless of role.
Plan
API access is included with the Premium and Enterprise plans. Keys can only be created on those plans. Some endpoints also depend on plan features — for example, ledger-entries-with-balance and ledger-totals need the Advanced Reports feature, and creating transactions is subject to your plan's document-type and monthly transaction limits. A request blocked by plan returns 403 Forbidden with a message naming the plan (see Errors).
Which branch the API uses
API keys are not tied to a branch, so requests act on the business's main (default) branch. Records that belong to a named branch are not returned by the list endpoints. A few read endpoints accept an explicit branchId (getTxnsWithFilters, getEarliestModifiedDate, and reportFilter.branchId on report endpoints) if you need to read a specific branch.
Current limitation: permissions are per endpoint, not per document type
Permissions are checked against the endpoint, not against the type of document in the request. For example, POST /txndata/upsertTxn is allowed if the role has Write permission on any transaction type, and then accepts any txnType your plan includes. Design your integration on the assumption that a key with write access to one document type can write others, and only give keys to integrations you trust.