Authentication
Every API call identifies itself in one of three ways. All three coexist: which one you use depends on who is calling — a person in a browser, an integration server, or a channel automating a task restricted to itself.
The three credentials
Dashboard session — a cookie issued when you sign in to /painel, valid only for that browser. It covers interactive use of the dashboard and the routes that explicitly require a session, such as API key management — a key can never create or revoke another key.
API key (hub_pk_...) — the credential designed for server-to-server integration. Sent in the Authorization: Bearer hub_pk_... header, it carries a scope list defined at creation time and can have an optional expiry. The secret is shown in full exactly once, when the key is created — if you lose it, the only way out is to revoke the key and create another. Revoking is immediate and permanent.
Channel token (hub_ch_...) — issued for one specific channel, with a fixed scope: channels:read, messages:send, templates:read and templates:write. It never authorizes another channel of the organization: using that token against a different channel id returns 404, not 403 — deliberately, so that an unauthorized attempt does not confirm that the other channel exists.
Scope per role
A dashboard session inherits the scopes of the user’s role in the organization. An API key can only be created with scopes the creating session already holds — you cannot delegate a scope you do not have.
| Role | Scopes |
|---|---|
| owner | * (all scopes) |
| admin | api_keys:read, api_keys:write, channels:read, channels:write, messages:send, templates:read, templates:write, webhooks:read, webhooks:write, billing:read, logs:read |
| developer | api_keys:read, api_keys:write, channels:read, templates:read, templates:write, webhooks:read, webhooks:write, logs:read |
| viewer | api_keys:read, channels:read, templates:read, webhooks:read, billing:read, logs:read |
The organization in the request
An API key and a channel token already carry the organization they belong to. A dashboard session does not — the same user can be a member of more than one organization.
- If the session belongs to a single organization, it is used automatically.
- If the session belongs to more than one, the
x-organization-idheader is required on every request.
x-organization-id header in that second case, the response is 400 ORGANIZATION_ID_OBRIGATORIO. Sending the id of an organization the user does not belong to returns 404 RECURSO_NAO_ENCONTRADO, not 403 — same principle as the channel token: never confirm the existence of something to someone who has no access to it.