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
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). |
contacts:read | GET de contatos. |
contacts:write | POST/PATCH de contatos. |
companies:read | GET de empresas. |
companies:write | POST/PATCH de empresas. |
webhooks:manage | Gerenciar assinaturas de webhook (em finalização — veja aviso abaixo). |
Webhooks ainda não lançados. O escopo webhooks:manage consta no catálogo, mas os
webhooks estão em finalização — não construa integrações de produção sobre eles ainda.
A documentação de verificação da assinatura (HMAC) dos payloads será publicada junto
com o lançamento público; até lá, não exponha um endpoint receptor em produção (sem
validar a origem, qualquer um que conheça a URL poderia injetar eventos falsos).
Leitura de pipelines. O endpoint GET /api-v1-pipelines exige o escopo
pipelines:read, que não é selecionável ao criar uma chave — hoje só chaves com
acesso total (*) leem pipelines. Como pipeline_id e stage_id são estáticos, o
caminho seguro é: crie uma chave * temporária, leia os pipelines uma vez, anote
os ids e revogue essa chave. Deixe a chave permanente da integração apenas com os
escopos operacionais (ex.: leads:write).
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.