Escopos mínimos
Princípio do menor privilégio aplicado a API keys. Quais escopos sua integração realmente precisa.
Dê à chave só os escopos que ela precisa para a operação atual. Se a integração só lê dados, não dê escopo de escrita. Se ela só toca contatos, não dê acesso a mensagens. Em caso de comprometimento da chave, o dano fica limitado.
Escopos disponíveis
| Escopo | Concede |
|---|---|
contacts:read | Listar e detalhar contatos; listar agendamentos, formulários e respostas de formulários |
analytics:read | Listar campanhas de disparo, automações e formulários (GET /forms aceita também contacts:read); ler os relatórios agregados (/analytics/reports/*) |
contacts:write | Criar e atualizar contatos |
deals:read | Listar e detalhar negócios; listar funis, equipe e tarefas |
deals:write | Criar negócios (e vincular/criar o contato) |
messages:read | Ler o texto das mensagens e buscas derivadas |
messages:write | Enviar mensagens WhatsApp (POST /messages/send) |
conversations:read | Listar conversas e equipe; com messages:read, ler as mensagens de uma conversa |
webhooks:write | Configurar webhooks de saída (reservado; sem endpoint ainda) |
Mapeamento por caso de uso
| Sua integração | Escopos necessários |
|---|---|
| Dashboard interno que mostra contatos | contacts:read |
| Busca de leads por termo de mensagem | contacts:read + messages:read |
| Agente IA com contexto do CRM | contacts:read + messages:read |
| Sincronização CRM → ERP (one-way) | contacts:read + messages:read |
| Sincronização ERP → CRM (criar/atualizar) | contacts:write |
| Captação de leads que viram negócio | deals:write |
| Relatório/BI de pipeline (ler negócios) | deals:read |
| Relatório de atendimento (ler conversas) | conversations:read |
| Análise do conteúdo das conversas | conversations:read + messages:read |
| Relatório de campanhas e automações | analytics:read |
| Relatórios de funil, atendimento, disparos e operação | analytics:read |
| Painel de tarefas da equipe | deals:read |
| Agenda e comparecimento | contacts:read |
| Respostas de formulários | contacts:read |
Quando faz sentido criar várias chaves
- Chaves separadas por integração — facilita revogação isolada e auditoria
- Chaves separadas por ambiente — staging e produção nunca devem compartilhar chave
- Chaves separadas por time — equipe X não precisa da chave da equipe Y
Não há limite de chaves ativas por organização. Crie quantas precisar.
Antipattern
❌ Uma única chave "admin" com todos os escopos para tudo.
Se essa chave vazar, todos os dados ficam expostos. Granularidade é defesa em profundidade.
Validando escopos no servidor
Toda chamada inclui validação no servidor: chave com escopo contacts:read tentando acessar endpoint que requer deals:read recebe 403 Forbidden com code: "missing_scope".
Os escopos requeridos por endpoint estão documentados na referência de cada um.