Identity and access
Scopes
Scopes decide which endpoints an API key opens. The catalogue is single-sourced and narrows to your licence.
A scope says what an API key can do. You pick scopes when you create the key; an endpoint whose scope you didn't select returns 403.
How it works
Scopes are shaped <resource>.<action>: contacts.read, conversations.write. An endpoint demands its scope; if your key lacks it, the request is refused.
{ "type": "error.list",
"errors": [{ "code": "forbidden", "message": "This key does not carry the contacts.write scope." }] }The * scope covers everything and is used only for audited administrative keys. For day-to-day integrations pick narrow scopes: the damage a leaked key can do is exactly the scope it carries.
The catalogue
The scope list lives in one place and three consumers read the same list: the panel that issues keys, the module that verifies them, and this documentation. What you see in the panel is what the server accepts.
The list narrows to your licence. Without a CRM subscription, contacts.* scopes never appear — a scope you can select but that opens no door would be a lie.
Fetch the live catalogue any time:
curl "https://accounts.blesyum.com/api/v1/apikeys/scopes" \
-H "Authorization: Bearer <session-token>"Core scopes
| Scope | Opens |
|---|---|
core.read | Reads core resources |
core.write | Creates / updates core resources |
CRM scopes
| Scope | Opens |
|---|---|
contacts.read · contacts.write | Contacts |
conversations.read · conversations.write | Conversations |
messages.write | Posts a message into a conversation |
events.read · events.write | Event stream |
data_attributes.read · data_attributes.write | Custom attribute definitions |
webhooks.manage | Manages webhook endpoints over the API |
Typos don't pass silently
Creating a key with a scope that isn't in the catalogue now returns 400. That gate is deliberate: there used to be no validation, so someone writing contats.read got a 201 and then spent days wondering why their key "didn't work".