---
title: "Permissions & scopes"
description: "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."
lang: en
url: https://developers.bodo-app.com/en/guides/scopes/
apiVersion: 2026-11-01
---

# 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

```text
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](/en/problems/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](/en/problems/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](/en/problems/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](/en/guides/errors/).