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.

json
{ "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:

bash
curl "https://accounts.blesyum.com/api/v1/apikeys/scopes" \
  -H "Authorization: Bearer <session-token>"

Core scopes

ScopeOpens
core.readReads core resources
core.writeCreates / updates core resources

CRM scopes

ScopeOpens
contacts.read · contacts.writeContacts
conversations.read · conversations.writeConversations
messages.writePosts a message into a conversation
events.read · events.writeEvent stream
data_attributes.read · data_attributes.writeCustom attribute definitions
webhooks.manageManages 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".

Bu sayfa işine yaradı mı?