# Permissions

Which scopes and access levels connections and customer replies need, and why they are never on a key by default.

Connections and replies handle data of third parties, so their four scopes are **privileged**: a key
only holds them if you tick them when you create it. A key created without choosing scopes does not.
The scope table is in [Scopes](/auth/scopes).

| Scope | Lets the key |
|---|---|
| `connections:read` | Read connections, and subscribe a webhook to `connection.*`. |
| `connections:write` | Connect and disconnect services. |
| `invoice-replies:read` | Read replies with their full text, download their attachments, and subscribe a webhook to `invoice.reply.*`. |
| `invoice-replies:write` | Register and delete replies. |

## Who can use them

The scope is a ceiling, and the role of the user who owns the key, or the
[access level](/multi-nif/managed-accounts#access-levels) of the account that manages the company, is a
second one.

| Who | `invoice-replies:read` | `invoice-replies:write` | `connections:read` and `:write` |
|---|---|---|---|
| `OWNER` and `ADMIN` of the account that owns the company | Yes | Yes | Yes |
| Member with a grant at `OPERATE`, and an account that manages the company at `OPERATE` | Yes | Yes | No |
| Member with a grant at `VIEW`, and an account that manages the company at `VIEW` | Yes | No | No |

What answers when something is missing:

| Status | Code | Cause |
|---|---|---|
| `403` | [`INSUFFICIENT_SCOPE`](/errors/INSUFFICIENT_SCOPE) | The key lacks the scope. |
| `403` | [`COMPANY_READ_ONLY`](/errors/COMPANY_READ_ONLY) | The role or access level is not enough: connections are for `OWNER` and `ADMIN` of the owning account, writing replies needs write access. |
| `403` | [`ACTIVE_COMPANY_NOT_ACCESSIBLE`](/errors/ACTIVE_COMPANY_NOT_ACCESSIBLE) | The company is not one of yours, or does not exist. Both answer the same. |

## Webhooks go to the owner

`connection.*` and `invoice.reply.*` events are delivered only to the endpoints of the account that
owns the company, never to an account that manages it. A managing account can still read the replies
with `GET …/invoice-replies` when it holds the scope.

## Related

<Related>

- [Scopes](/auth/scopes): the full catalog
- [Managed accounts](/multi-nif/managed-accounts): access levels over a company
- [Connections](/guides/connections): what the write scope does

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi