Autenticação
Toda chamada à API se identifica de uma entre três formas. As três coexistem: a escolha depende de quem está chamando — uma pessoa no navegador, um servidor de integração, ou o próprio canal automatizando uma tarefa restrita a si mesmo.
As três credenciais
Sessão do painel — um cookie emitido ao entrar em /painel, válido só para o navegador. Serve para o uso interativo do painel e para as rotas que exigem explicitamente uma sessão, como a gestão de chaves de API — uma chave nunca pode criar ou revogar outra chave.
Chave de API (hub_pk_...) — a credencial pensada para integração servidor a servidor. Enviada no header Authorization: Bearer hub_pk_..., carrega uma lista de escopos definida na criação e pode ter uma expiração opcional. O segredo aparece por inteiro uma única vez, no momento em que a chave é criada — se ele se perder, a única saída é revogar a chave e criar outra. Revogar é imediato e definitivo.
Token de canal (hub_ch_...) — emitido para um canal específico, com escopo fixo: channels:read, messages:send, templates:read e templates:write. Ele nunca autoriza outro canal da organização: usar esse token para acessar o id de um canal diferente do que o emitiu responde 404, não 403 — de propósito, para uma tentativa de acesso indevido não confirmar que o outro canal existe.
Escopo por papel
Uma sessão do painel herda os escopos do papel do usuário na organização. Uma chave de API só pode ser criada com escopos que a sessão que a criou já possui — não é possível delegar um escopo que não se tem.
| Papel | Escopos |
|---|---|
| owner | * (todos os escopos) |
| 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 |
A organização na requisição
Uma chave de API e um token de canal já carregam a organização a que pertencem. Uma sessão do painel, não — o mesmo usuário pode ser membro de mais de uma organização.
- Se a sessão pertence a uma única organização, ela é usada automaticamente.
- Se a sessão pertence a mais de uma, o header
x-organization-idé obrigatório em toda requisição.
x-organization-id nesse segundo caso, a resposta é 400 ORGANIZATION_ID_OBRIGATORIO. Enviar um id de organização à qual o usuário não pertence responde 404 RECURSO_NAO_ENCONTRADO, não 403 — mesmo princípio do token de canal: não confirmar a existência de algo a quem não tem acesso a isso.