Permissions & scopes
What a call may do is the intersection of the principal’s roles, the key’s scope and the organization’s ceiling. It is computed fresh on every call.
The intersection
effective = roles of the principal
∩ scope of the key
∩ permissions when the key was created
∩ API ceiling of the organization
∩ AI mandate (personal keys only)A scope can only take away, never add. When the person loses a role, the key loses it on the next call too.
Resource scopes
Per resource: no access, read, or read and write.
| Resource | Read | Write |
|---|---|---|
Contacts · contacts | contacts:read | contacts:write |
Companies · companies | companies:read | companies:write |
Tasks · tasks | tasks:read | tasks:write |
Documents · documents | documents:read | documents:write |
Invoices · invoices | invoices:read | invoices:write |
Time entries · time_entries | time_entries:read | time_entries:write |
Webhook endpoints · webhook_endpoints | webhook_endpoints:read | webhook_endpoints:write |
Families
Consequential actions belong to families. Each one is blocked until you allow it on the key one by one.
| Family | What belongs to it | Allowing it needs |
|---|---|---|
| Delete | deleting records | an IP rule on the key; 10/min and 300 per day |
| Money | changing bookings and amounts | an IP rule; level of the AI mandate |
| Finalize documents | finalizing invoices | an IP rule; level of the AI mandate |
| Send | sending invoices and documents | an IP rule; level of the AI mandate |
| Money runs | starting dunning and payment runs | an IP rule; level of the AI mandate |
When a family is blocked, the API answers 403 RISK_FAMILY_BLOCKED. There is no confirmation round trip through the API: what needs a confirmation in the web app or through MCP is blocked here. A batch allows no money family (BATCH_FAMILY_NOT_ALLOWED).
IP rule
- Required for every write scope and every allowed family; without an IP rule a key is read-only at most.
- Up to 32 networks in CIDR notation, IPv4 at least /24, IPv6 at least /48.
- Private networks, loopback and link-local are not allowed.
- A call from outside ends as 401; the owner gets an email and a bell entry at most once per hour.
API level of the organization
| Level | Effect |
|---|---|
| off | no call at all, not even reads |
| read | reads only; writes end with 403 FORBIDDEN |
| on | reads and writes along the scopes; needs consent to the terms of use |
How the preview module comes first is shown in the matrix under Errors.