Chaves de API
Uma chave de API permite que o site, o aplicativo ou o seu servidor trabalhe com o projeto sem entrar na interface: enviar eventos, ler perfis e gerenciar segmentos, jornadas e campanhas. As chaves são criadas e revogadas em “Configurações” → “Chaves de API”.
A seção fica visível para “Proprietário”, “Administrador” e “Gerente”. Criar e revogar chaves é permitido para “Proprietário” e “Administrador”.

Tipos de chave
| Write | Secret | |
|---|---|---|
| Começa com | cdp_wk_ |
cdp_sk_ |
| O que permite | apenas enviar eventos | enviar eventos e executar ações no projeto, conforme as permissões escolhidas |
| Onde usar | código do site, aplicativo móvel, servidor | somente no seu servidor |
| Pode ser exposta a terceiros | sim, ela aparece no código das páginas do site | não, mantenha-a em segredo |
| Limite de requisições | 6000 por minuto | 1200 por minuto (padrão) |
A chave de gravação (Write) é pública por natureza: ela fica no código de cada página do site. Com ela só é possível enviar eventos, então um vazamento não dá acesso aos dados. Para impedir que outro site envie eventos em seu nome, você pode informar na seção Site → Conexão os domínios dos quais a chave é aceita; veja Conexão do site.
A chave secreta (Secret) dá acesso aos dados do projeto pelo servidor. Nunca a coloque no código das páginas, em aplicativos móveis ou em repositórios públicos.
Como criar uma chave
- Abra “Chaves de API”.
- No cartão “Nova chave”, informe o “Nome”: por ele você vai saber depois onde a chave é usada, por exemplo “Site” ou “Servidor da loja virtual”.
- Escolha o “Tipo”: “Gravação” (Write) ou “Secreta” (Secret).
- Para a chave secreta, marque as “Permissões da chave”: apenas o que a integração realmente precisa.
- Clique em “Criar chave”.

Logo após a criação, a chave completa aparece no topo da página. Clique em “Copiar” e guarde-a, por exemplo em um gerenciador de senhas ou nas variáveis de ambiente do servidor. A chave secreta é exibida apenas uma vez: guardamos somente a impressão digital dela, e não é possível recuperá-la. Se você a perder, crie uma nova e revogue a antiga.
É mais prático criar a chave de gravação do site diretamente na seção Site → Conexão: lá ela já entra no código de instalação e fica disponível a qualquer momento; veja Conexão do site.
Na tabela de chaves aparecem o nome, quem criou e quando, o tipo, o início da chave (por exemplo, cdp_sk_a1b2…), o número de permissões e a data do último uso.
Permissões da chave secreta
Você só pode conceder à chave as permissões que você mesmo possui. As permissões valem para o projeto inteiro: não é possível limitar a chave a jornadas ou segmentos específicos.
| Permissão | O que libera |
|---|---|
| Ler perfis | perfil por identificador e os eventos dele |
| Dados pessoais sem máscara | e-mail, telefone e outros dados pessoais sem máscara; sem essa permissão, eles são mascarados |
| Alterar perfis e consentimentos | consentimentos para mensagens, vínculo com o Telegram |
| Excluir perfis (GDPR) | exclusão do perfil a pedido do cliente |
| Catálogo de eventos e atributos | lista de eventos e de propriedades dos perfis |
| Alterar o esquema de eventos | substituição do esquema de eventos do projeto, veja Esquema de eventos |
| Ler / alterar segmentos | visualizar, criar, alterar, excluir e recalcular segmentos |
| Ler jornadas e relatórios; editar rascunhos e inscrever participantes; publicar, pausar e arquivar jornadas | trabalho com jornadas |
| Ler campanhas e relatórios; criar e editar campanhas; lançar, pausar e cancelar campanhas | trabalho com campanhas |
| Ler o catálogo de produtos e as recomendações; enviar e excluir produtos | produtos e recomendações |
| Envio de mensagens avulsas | mensagens transacionais e cascatas a partir do seu servidor; veja Mensagens transacionais e cascatas |
| Análises | cálculo de relatórios, leitura de relatórios salvos e painéis, relatório da jornada |
| Relatórios salvos e painéis | criação, alteração e exclusão de relatórios salvos e painéis; veja Painéis e envio de relatórios |
| Conversas do chat; respostas no chat e encerramento de conversas | leitura de conversas e respostas aos clientes em nome da chave, para bots e helpdesk; veja Chat online |
Exemplo: para uma chave que sincroniza clientes VIP a partir do CRM, bastam as permissões “Ler segmentos” e “Alterar segmentos”.
Todas as ações realizadas com uma chave secreta ficam registradas no log de auditoria do projeto em nome da chave; veja Configurações do projeto, plano e auditoria.
Como revogar uma chave
- Encontre a chave na tabela e clique em “Revogar”.
- Confirme a ação.
As requisições com essa chave param de funcionar na hora (resposta 401). A chave revogada continua na lista com a marca “Revogada”, para que o histórico dela fique visível. Não é possível reativá-la; se precisar, crie uma nova.
Revogue a chave imediatamente se ela puder ter chegado a terceiros, se um funcionário com acesso a ela tiver saído da empresa ou se a integração não for mais usada.
O que é importante saber
- Limites. Ao exceder o limite de requisições ou a cota mensal de eventos do plano, a API responde
429. Distribua os envios de forma uniforme e repita a requisição após uma pausa. - Troca segura da chave. Crie uma nova chave, atualize-a no servidor, verifique se as requisições estão chegando (campo “Último uso”) e só então revogue a antiga.
- Uma chave para cada integração. Assim o log de auditoria mostra quem fez o quê e, em caso de vazamento, basta revogar uma chave.
- Para saber como enviar eventos e chamar a API pelo servidor, veja o artigo Integração pelo servidor.
- A chave secreta também serve para conectar um assistente de IA, como o Claude Code; veja Assistentes de IA (MCP).