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ão 403. Isso é intencional: um 403 diria "existe, mas não é seu", revelando a existência de um registro que aquela chave não deveria enxergar.

Consequência prática: um 404 desta API pode significar "não existe" ou "existe, mas não é seu" — e a resposta não distingue os dois casos.