Chaves e escopos
Como criar, listar e revogar API Keys, e o catálogo de escopos (permissões) que cada chave pode ter.
As API Keys são gerenciadas dentro do app, por um usuário administrador ou gestor do workspace. Não há endpoint REST público para criar chaves — isso protege a operação de gestão atrás do login do CRM.
Criar uma chave
A API pública é um recurso do plano do workspace. Se o seu plano não a inclui, a criação de chaves é bloqueada — fale com a Vendee para habilitar.
No Vendee, vá em Configurações → Integrações / API e crie uma nova chave informando:
- Nome — um rótulo para você reconhecer a chave (ex.: "Make – formulário", até 120 caracteres).
- Escopos — a lista de permissões (veja abaixo). Selecione sempre ao menos um escopo, escolhendo só o que a integração precisa.
Omitir escopos equivale a acesso total. Se você criar uma chave sem marcar nenhum
escopo, ela nasce com * — leitura e escrita irrestritas em todos os recursos do
workspace. Isso é o oposto do menor privilégio: trate uma chave * como credencial de
administrador e prefira sempre escopos explícitos e mínimos.
Ao criar, o CRM retorna a chave em texto puro (vnd_...) uma única vez. Copie e
guarde com segurança — depois disso só fica o hash, e a chave não pode ser recuperada.
Cada chave registra também quem a criou. Esse usuário é usado como responsável padrão
quando um lead ou negócio entra sem owner_id explícito. Crie chaves com um usuário que
faça sentido como dono dos registros que entram por ela.
Listar e revogar
Na mesma tela você vê as chaves do workspace — com nome, prefixo, escopos, data de criação,
último uso e status (active ou revoked). O hash nunca é exibido.
Para desativar uma chave, use Revogar. A revogação é imediata: a chave passa a
responder 401 revoked_api_key em qualquer requisição. A operação é idempotente (revogar
de novo não altera a data original de revogação) e preserva a trilha de auditoria — não há
"des-revogar"; gere uma nova chave.
Escopos disponíveis
Um escopo autoriza um conjunto de operações. A regra é simples: a chave tem permissão se
seus escopos incluem * ou o escopo exato exigido pelo endpoint.
| Escopo | Permite |
|---|---|
* | Acesso total — todos os endpoints (inclusive leitura de pipelines). |
leads:write | POST em api-v1-leads (entrada de leads). |
deals:read | GET de negócios (lista e detalhe). |
deals:write | POST/PATCH de negócios + ações (win, lose, move-stage). |
activities:read | GET de atividades (lista e detalhe). |
activities:write | POST/PATCH de atividades. |
notes:read | GET de notas (lista e detalhe). |
notes:write | POST de notas. |
contacts:read | GET de contatos. |
contacts:write | POST/PATCH de contatos. |
companies:read | GET de empresas. |
companies:write | POST/PATCH de empresas. |
webhooks:manage | Criar, listar e remover assinaturas de webhook. |
pipelines:read | GET de funis e etapas. |
Webhooks disponíveis. O escopo webhooks:manage autoriza a gerenciar assinaturas.
O catálogo de eventos, o formato do payload, os cabeçalhos, a verificação da assinatura
(HMAC) e a régua de reenvio estão em Webhooks. Valide sempre a
assinatura no seu endpoint receptor: sem isso, qualquer um que descubra a URL poderia
injetar eventos falsos.
Envios de webhook
Na mesma tela, abaixo das chaves, fica Envios de webhook: os últimos 50 envios que o CRM tentou fazer para os endereços cadastrados, com quatro colunas — o evento, a situação (Entregue, Não entregue, Tentando de novo, Na fila), a resposta do seu servidor e quando. Quando houve mais de uma tentativa, o número aparece ao lado da situação.
É por aqui que se descobre por que um webhook parou de chegar sem precisar abrir chamado: se o seu servidor recusou, se não respondeu a tempo, ou se a entrega nem chegou a sair.
Com a API pública desligada no plano, a tela abre mesmo assim, em modo de consulta, com um aviso explicando que nada está sendo entregue. É proposital: esconder a tela esconderia justamente a explicação do problema.
Boas práticas
- Menor privilégio. Dê só os escopos que a integração precisa. Um formulário de site
costuma precisar apenas de
leads:write. - Uma chave por integração. Facilita revogar uma sem derrubar as outras e rastrear o uso pelo "último uso".
- Rotação. Se suspeitar de vazamento, revogue e gere outra — a troca é barata.