Escopos & Permissões

Uma API Key não herda automaticamente tudo que a conta que a criou pode fazer — ela recebe uma lista explícita de escopos escolhida na criação. Cada requisição é checada contra os escopos daquela chave, sem exceção: diferente do usuário dono da empresa no aplicativo Maestron, uma chave nunca tem bypass — mesmo uma chave criada pelo dono só pode o que os escopos concedidos a ela permitem.

Catálogo de escopos

Escopo	Nome	O que libera
crm.view	Ver CRM	Listar e obter negócios, pipelines, estágios e atividades.
crm.leads.create	Criar negócios	POST /crm/deals.
crm.leads.edit	Editar negócios	PATCH/DELETE de negócios, mover de etapa, e o CRUD de atividades.
crm.leads.delete	Excluir negócios	DELETE /crm/deals/{id}.
crm.leads.transfer	Transferir negócios	Definir/alterar assignee_id e mudar funnel_id de um negócio já criado.
crm.leads.close	Fechar negócios	Marcar como ganho, perdido, reabrir, e mudar status para um valor de kind ganho/perdido via PATCH.
crm.funnels.manage	Gerenciar pipelines	CRUD de pipelines (/crm/pipelines), incluindo seus estágios.
crm.catalog.manage	Gerenciar catálogo	Escrita de /crm/catalog-items (leitura usa crm.view).
crm.quotes.manage	Gerenciar orçamentos	Concessível na chave, mas sem endpoint público correspondente hoje.
crm.inbound.link	Vincular e-mails	Concessível na chave, mas sem endpoint público correspondente hoje.
customers.view	Ver clientes	Listar e obter companies (/crm/companies) e contacts (/crm/contacts).
customers.manage	Gerenciar clientes	POST/PATCH/DELETE de companies e contacts.

Dois escopos sem endpoint ainda

crm.quotes.manage e crm.inbound.link aparecem na tela de criação de chave porque fazem parte do catálogo geral de permissões do CRM, mas nenhum endpoint da API pública os usa no momento — conceder um deles a uma chave não libera nenhuma chamada adicional.

Escopo por endpoint

Método	Path	Escopo exigido
GET	/crm/deals, /crm/deals/{id}, /crm/deals/{id}/activities	crm.view
GET	/crm/pipelines, /crm/pipelines/{id}, /crm/pipelines/{id}/stages	crm.view
GET	/crm/activities, /crm/activities/{id}	crm.view
POST	/crm/deals	crm.leads.create
PATCH	/crm/deals/{id}	crm.leads.edit (+ crm.leads.transfer se mudar funnel_id/assignee_id; + crm.leads.close se mudar status para kind ganho/perdido)
DELETE	/crm/deals/{id}	crm.leads.delete
PATCH	/crm/deals/{id}/stage	crm.leads.edit
POST	/crm/deals/{id}/win, /lose, /reopen	crm.leads.close
POST	/crm/pipelines	crm.funnels.manage
PATCH	/crm/pipelines/{id}	crm.funnels.manage
DELETE	/crm/pipelines/{id}	crm.funnels.manage
POST	/crm/activities	crm.leads.edit
PATCH	/crm/activities/{id}	crm.leads.edit
DELETE	/crm/activities/{id}	crm.leads.edit
POST	/crm/activities/{id}/complete, /reopen	crm.leads.edit
GET	/crm/catalog-items, /crm/catalog-items/{id}	crm.view
POST/PATCH/DELETE	/crm/catalog-items...	crm.catalog.manage
GET	/crm/companies, /crm/companies/{id}, /crm/contacts, /crm/contacts/{id}	customers.view
POST/PATCH/DELETE	/crm/companies..., /crm/contacts...	customers.manage
GET	/crm/events	crm.view (+ feature de plano integrations.webhooks)

Escopo fino dentro de um mesmo endpoint

PATCH /crm/deals/{id} aceita vários campos com um único escopo base (crm.leads.edit), mas dois deles exigem escopo adicional: informar assignee_id (responsável) ou mudar funnel_id exige crm.leads.transfer; mudar status para um valor cujo tipo (kind) seja ganho ou perdido exige crm.leads.close. Sem o escopo fino, a resposta é 403 mesmo com crm.leads.edit concedido.

Resposta quando o escopo falta

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

Status 403. Diferente de um recurso de outra empresa (que responde 404, nunca 403 — ver Erros), a falta de escopo é sempre 403: ela não revela nem esconde a existência do recurso, apenas nega a operação.

Para o passo a passo de escolher escopos na criação da chave, veja Gerando sua API Key.