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” 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”: 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 |
| 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 |
| Análises | relatórios |
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.