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 |
contacts:write | Criar e editar contatos (em desenvolvimento) |
messages:read | Ler mensagens e conversas |
messages:write | Enviar mensagens (em desenvolvimento) |
webhooks:manage | Configurar webhooks de entrada (planejado) |
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 (em desenvolvimento) | contacts:write |
| Bot de resposta automática (planejado) | messages:read + messages:write |
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 messages:write recebe 403 Forbidden com code: "missing_scope".
Os escopos requeridos por endpoint estão documentados na referência de cada um.