Autenticação
Chaves de API, contas de serviço e escopos.
Toda chamada à /api/v1 leva um token no cabeçalho Authorization:
Authorization: Bearer sk_live_…O token é de um destes tipos:
| Token | Para quê | Age como |
|---|---|---|
Chave de API (sk_live_…) | Integrações entre sistemas: ERP, BI, seu backend | A conta de serviço da chave, com alcance no workspace inteiro, limitado aos escopos da chave |
| Access token OAuth | Apps que agem em nome de uma pessoa | O membro que autorizou o app, limitado aos escopos concedidos e às permissões do papel dele. Veja OAuth |
Sem token, ou com um token desconhecido, expirado ou revogado, a resposta é 401 com o código unauthorized.
Chaves de API
Owner e Admin criam e revogam chaves em Configurações → Desenvolvedores → API Keys. O passo a passo está no começo rápido.
- O formato é
sk_live_seguido de 32 caracteres hexadecimais. - A chave aparece uma única vez, ao ser criada. O Zaplin guarda só um hash e os primeiros caracteres, que a lista mostra para você reconhecer a chave.
- Prazos: 30 dias, 90 dias, 1 ano ou Nunca. A lista marca Expira em breve nos últimos 30 dias, e uma chave expirada para de autenticar.
- Revogar vale na hora e não dá para desfazer: quem usa a chave passa a receber
401. - Cada chave faz até 600 requisições por minuto. Veja limites.
Contas de serviço
Uma conta de serviço é a identidade de um sistema, não de uma pessoa. Cada chave pertence a uma, e as ações feitas com a chave aparecem na auditoria com o nome da conta. A chave alcança o workspace inteiro, limitada aos seus escopos.
Alguns endpoints são feitos para uma pessoa e recusam chaves com 403: os rascunhos de automação, formulário e segmento (POST /v1/automations, POST /v1/forms e POST /v1/segments/rules) pedem um token OAuth.
Escopos
Um escopo libera leitura (:read) ou escrita (:write) de um domínio. Não existe escopo amplo: marque só o que a integração usa. Uma chamada sem o escopo da rota recebe 403 com o código forbidden.
Para um token OAuth, o membro que autorizou também precisa ter a permissão na coluna da direita. Um token alcança a interseção dos dois.
| Escopo | Permissão do membro (OAuth) |
|---|---|
numbers:read / numbers:write | numbers.read / numbers.manage |
contacts:read / contacts:write | contacts.read / contacts.write |
conversations:read / conversations:write | conversations.read / conversations.assign |
messages:read / messages:write | conversations.read / conversations.reply |
groups:read / groups:write | groups.read / groups.send |
pipelines:read / pipelines:write | pipelines.read / pipelines.move |
reminders:read / reminders:write | reminders.read / reminders.create |
automations:read / automations:write | automations.read / automations.activate |
webhooks:read / webhooks:write | developers.read / developers.manage |
campaigns:read / campaigns:write | campaigns.read / campaigns.create |
campaigns:send | campaigns.send |
forms:read / forms:write | forms.read / forms.write |
segments:read / segments:write | contacts.read / contacts.write |
members:read | members.read |
Algumas rotas pedem uma permissão mais estreita que a do escopo, como contacts.delete para excluir um contato ou conversations.close para fechar uma conversa. A referência mostra o escopo de cada uma.
campaigns:send é de alto risco
Envios em massa são o maior risco de bloqueio dos números pelo WhatsApp. Marque campaigns:send só se a integração precisa enviar campanhas.