Autenticação
Como autenticar suas chamadas com uma API key e quais escopos existem.
Toda chamada à API v1 exige uma API key enviada no header Authorization, no formato Bearer <sua-key>.
Authorization: Bearer <sua-key>Criando uma chave
As chaves são criadas em Configurações → API, dentro da plataforma. Ao criar uma chave, você define um nome (para identificá-la depois) e os escopos que ela terá — cada escopo concede acesso a uma capacidade específica da API.
O valor da chave é exibido apenas uma vez, no momento da criação. Guarde-o em um local seguro — não é possível recuperá-lo depois; se perder o valor, é necessário criar uma nova chave.
Escopos disponíveis
| Escopo | Nome | Descrição |
|---|---|---|
| contacts:read | Leitura de contatos | Listar e consultar contatos, incluindo tags e campos personalizados. |
| contacts:write | Escrita de contatos | Criar, atualizar e deletar contatos. |
| tags:read | Leitura de tags | Listar as tags disponíveis na empresa. |
| tags:write | Escrita de tags | Criar, atualizar e deletar tags, e aplicá-las a contatos. |
| custom_fields:read | Leitura de campos personalizados | Listar as definições de campos personalizados da empresa. |
| custom_fields:write | Escrita de campos personalizados | Criar, atualizar e deletar definições de campos personalizados. |
| campaigns:read | Leitura de campanhas | Listar campanhas, destinatários e status de envio. |
| campaigns:write | Escrita de campanhas | Criar, atualizar, iniciar, pausar e retomar campanhas. |
| messages:read | Leitura de mensagens | Consultar o histórico de mensagens das conversas. |
| messages:send | Envio de mensagens | Enviar mensagens e templates para contatos. |
| connections:read | Leitura de conexões | Listar as conexões de WhatsApp e Instagram da empresa. |
| pipeline:read | Leitura do pipeline | Consultar os estágios do pipeline de CRM. |
| lead_memory:read | Leitura da memória do lead | Consultar a memória que a IA mantém do contato (resumo, sentimento, BANT, fatos, objeções). |
| bulk:write | Importação em massa de contatos | Enfileirar importações em massa de contatos (processamento assíncrono). |
Revogação
Uma chave pode ser revogada a qualquer momento em Configurações → API. A revogação é imediata: chamadas feitas com a chave revogada passam a ser rejeitadas.
Nunca exponha sua API key em código executado no navegador (front-end) nem a inclua em repositórios versionados. Trate-a como uma senha. Se uma chave vazar, revogue-a imediatamente e crie uma nova.
Chaves legadas
Chaves migradas do antigo token único da empresa (companies.api_token) aparecem marcadas como legadas e recebem, automaticamente, as capacidades que esse token já possuía — nunca escopos de escrita/deleção/importação em massa adicionais, que exigem concessão explícita.
Chaves legadas ainda aceitam o token via query string (?api_token=<token>) por compatibilidade, mas esse método está descontinuado — o token fica exposto em logs de acesso — e será removido. Chaves novas só autenticam pelo header Authorization: Bearer; usar ?api_token= com uma chave nova resulta em erro. Migre para o header o quanto antes.