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.
| 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 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 | The key lacks the scope. |
403 | 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 | 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
Delete and retention
How long BeeL. keeps customer replies, how to delete one to answer an erasure request, and what your webhook endpoint must do when it hears about it.
Bulk operations and exports
Issue, mark, download, email and export many invoices at once, and create or delete customers and products in batches — and how to read what came back.