Scopes (permissões)

Scopes controlam exatamente o que uma API Key pode fazer. Em vez de “chave administrativa total”, você escolhe permissões granulares por recurso e por operação (leitura vs escrita).

Convenção de nomes

Os scopes seguem o padrão <recurso>:<ação>:

• contacts:read — listar contatos, buscar por id
• contacts:write — criar, atualizar, deletar contatos
• deals:read — listar/ver negócios
• deals:write — criar/atualizar/deletar negócios

write é sempre cumulativo: cobre POST, PATCH e DELETE no recurso. Não há scopes separados pra criar vs deletar — quem cria pode também deletar.

Catálogo completo

Recursos CRM core

Scope	Permite
contacts:read	GET /contacts, GET /contacts/:id, POST /contacts/search
contacts:write	POST/PATCH/DELETE em contacts
companies:read	GET listagem e detalhe de empresas
companies:write	Mutações em empresas
deals:read	GET listagem e detalhe de negócios
deals:write	Mutações em negócios
activities:read	GET atividades vinculadas a um contato/empresa/deal
activities:write	Criar/atualizar atividades, registrar ligações, e-mails, tarefas

Sales

Scope	Permite
proposals:read	Listar/ver propostas
proposals:write	Criar/atualizar propostas

Configurações e catálogos

Scope	Permite
pipelines:read	Listar pipelines e suas etapas (útil pra criar deals com stageId correto)
properties:read	Listar propriedades customizadas de contact/company/deal
tags:read	Listar tags
tags:write	Criar/atualizar tags
lists:read	Listar listas estáticas/dinâmicas
lists:write	Manipular membros de listas estáticas

Forms

Scope	Permite
forms:read	Listar formulários configurados
forms:submissions:read	Ler submissions de formulários

Webhooks (saída)

Scope	Permite
webhooks:manage	CRUD de webhooks que disparam quando eventos do CRM acontecem

Wildcard

Scope	Permite
*	Todos os scopes acima + scopes futuros

Cuidado com `*`

O wildcard * é o equivalente a “root” — qualquer endpoint da API. Use apenas pra integrações internas full-trust (ex: script de migração rodando dentro da sua infra). Para Zapier, Make, n8n etc., marque scopes específicos.

Como o guard avalia

Quando uma request chega:

1. Endpoint sem @RequireScopes decorator? Bloqueado pra API Key. Esses endpoints só são acessíveis via UI logada (JWT).
2. Key tem *? Libera qualquer scope, qualquer endpoint marcado.
3. Key tem todos os scopes exigidos? Libera.
4. Falta algum scope? 403 insufficient_scope com mensagem indicando qual falta.

Exemplo: POST /contacts exige contacts:write. Uma key com apenas contacts:read recebe:

{
  "error": "insufficient_scope",
  "message": "Scope insuficiente. Necessário: contacts:write",
  "required": ["contacts:write"],
  "have": ["contacts:read"]
}

Princípio do menor privilégio

Ao criar uma chave, marque só os scopes que a integração realmente precisa:

• Integração só lê? Apenas *:read
• Webhook recebe leads e cria contatos? Apenas contacts:write
• Cria deals quando lead vira oportunidade? contacts:read + deals:write + pipelines:read (pra saber stageId correto)

Quanto menos privilégio, menor o impacto se a chave vazar.

Mudanças no catálogo

O catálogo de scopes está versionado junto com a API. Novos scopes podem ser adicionados a qualquer momento — keys existentes não são afetadas. Scopes nunca são removidos sem deprecation prévio (mínimo 90 dias de aviso).

Pra acompanhar mudanças, veja o changelog (público) ou se inscreva nas notificações do CRM.