Permissões
São duas camadas, e as duas precisam liberar a chamada — além de o plano da conta incluir o módulo (sem ele, 403 module_not_in_plan, veja a tabela abaixo).
São duas camadas, e as duas precisam liberar a chamada — além de o plano da conta incluir
o módulo (sem ele, 403 module_not_in_plan, veja a tabela abaixo).
Camada 1 — os escopos da chave. Você escolhe na criação (e pode editar depois) o que aquela
chave pode fazer: contacts:read, deals:write, etc. A lista completa está na
seção 24. Faltou escopo → 403 forbidden_scope.
Camada 2 — as permissões do responsável pela chave. Toda chave tem uma pessoa responsável por ela, mostrada na tela de chaves — normalmente quem a criou, mas nem sempre: quando a chave é aberta por alguém que não é membro da conta, o responsável é escolhido entre as pessoas da conta no momento da criação. A chave herda as permissões de módulo do responsável, resolvidas a cada chamada — não congeladas no dia em que a chave nasceu. Se você mudar as permissões dessa pessoa em Configurações → Usuários, o comportamento da chave muda junto, já na chamada seguinte.
⛒ É por isso que "mudei a permissão e nada aconteceu" costuma ser eixo trocado: confira na tela de chaves quem é o responsável e mude a permissão dele, não a de quem clicou em criar.
| O que acontece | Resposta |
|---|---|
| O plano da conta não inclui aquele módulo | 403 module_not_in_plan — vale até para o dono da conta; nenhuma permissão destrava, só contratar o módulo |
| O responsável pela chave não é mais membro ativo da conta | 403 key_actor_invalid — crie uma chave nova |
| A pessoa tem "Não pode" naquele módulo | 403 forbidden_module — mesmo com o escopo presente |
| A pessoa tem "Só o dele" | A chave só enxerga o que é dela (veja abaixo) |
| A pessoa tem "Tudo" | Sem restrição |
O que "Só o dele" faz na prática
- Listagens recortam em silêncio. Registros de outro responsável simplesmente não aparecem — sem erro, sem contagem separada.
- Um item de outro responsável responde
404, não403. Isso é intencional: um403diria "existe, mas não é seu", revelando a existência de um registro que aquela chave não deveria enxergar.
Consequência prática: um
404desta API pode significar "não existe" ou "existe, mas não é seu" — e a resposta não distingue os dois casos.