Scopes, roles and businesses

Three things decide whether a call succeeds: the scopes the token carries, the role of the person who connected it, and the business it was granted. All three are checked on every request.

Scopes

Scope	Customers see	Allows
`read`	See your books	Accounts, transactions, contacts, invoices, bills, receipts and reports for this business.
`write`	Add, change and remove records	Create, edit, void and remove transactions, invoices, bills, contacts and payments, and subscribe to webhooks.
`delete`	Delete tracking tags	Permanently delete the dimensions (tags such as class or location) used to categorise entries.

Each operation in the API reference names its scope in x-required-scope. A token without it gets 403 INSUFFICIENT_SCOPE. Register only the scopes your app needs — the consent screen lists them, and fewer is more likely to get a yes.

Roles

A token acts as the person who connected it, with their role in that business:

Role	Can grant	Notes
owner	read, write, delete	Also webhook subscriptions and period locks. Sees and can end every connection to their business.
bookkeeper	read, write, delete	Everything that writes to the books.
accountant	read only	If an accountant approves an app asking for write, the connection is read-only (the consent screen says so).

A role refusal is 403 FORBIDDEN (or role_not_permitted). Operations that need a particular role say so in x-allowed-roles.

One business per connection

The person picks one business on the consent screen. The token reaches that business and nothing else, even when the person belongs to several:

Calls that do not name a business act on the granted one.
Naming another one — ?entity_id=, an entity_id in the body, or an X-Entity-Id header — is 403 ENTITY_NOT_GRANTED, with error.details.granted_entity_id.
Another business's record id is 404, exactly as if it did not exist.
GET /api/v1/entities lists just the granted business.

To work with several businesses, have the person connect each one; you will get one token pair per business.

Not available to apps

Routes about the person's own account answer 403 NOT_AVAILABLE_TO_APPS to an app token: API key management (/keys), switching the active business (/entities/switch), invitations, push-device registration, notification preferences, and the password login endpoints (/auth/*).

Apps can read a business's invoice branding and its customer statements, but cannot change the business details or logo printed on invoices, or email a customer a statement (PUT /entities/branding, POST/DELETE /entities/branding/logo, POST /contacts/{id}/statement/send): those answer the same 403.