Chaves de API do WhatsApp: autenticação, ambientes e rotação

A autenticação na API do WhatsApp do Joinotify é por Bearer token: uma chave de API enviada no cabeçalho Authorization de cada requisição. O segredo completo aparece uma única vez, na criação — só o hash fica salvo no servidor. Perder o segredo significa criar uma chave nova e revogar a antiga; não há recuperação.

curl https://api.joinotify.com/messages \
  -H 'Authorization: Bearer sk_live_xxx'

Anatomia da chave

A chave tem um prefixo visível — algo como sk_live_AbCdEf — e um segredo completo que só você vê uma vez. O prefixo é o que aparece no painel e nos logs: ele identifica a chave sem revelá-la.

Consequência prática: registre o prefixo nos seus logs, nunca o segredo. É o suficiente para saber qual chave fez o quê.

Onde guardar

• Variável de ambiente — o mínimo aceitável.
• Cofre de segredos — o certo, com acesso auditado.
• Nunca no repositório — nem em arquivo de exemplo, nem em comentário, nem no histórico do Git.
• Nunca no front-end — chave em JavaScript de navegador é chave pública.
• Nunca no blueprint de automação — cenários do Make e workflows do n8n são exportados e compartilhados.

A pergunta que vale a pena fazer: se este arquivo virasse público agora, o que um estranho conseguiria enviar em nome da minha empresa?

Uma chave por consumidor

Uma chave para tudo é conveniente até o dia em que você precisa revogar. Separe por quem usa:

1. Uma chave para a aplicação de produção.
2. Uma para o ambiente de testes.
3. Uma por integração de terceiro — a automação, o plugin, o script de importação.
4. Uma por parceiro externo, quando existir.

Assim, revogar a chave que vazou no repositório de uma agência não derruba a loja. Com chave única, qualquer incidente vira indisponibilidade geral.

Separando ambientes

Ambiente de teste e produção precisam de chaves distintas — e, idealmente, de números distintos. Duas razões concretas:

• Mensagem de teste enviada para cliente real é um incidente de imagem, e acontece.
• A qualidade do número de produção é afetada por qualquer envio ruim, inclusive de teste.

Vale também travar no código: se a chave é de produção e o ambiente não é, recuse o envio antes de chamar a API.

Rotação sem downtime

1. Crie a chave nova e guarde no cofre.
2. Publique a aplicação lendo a chave nova.
3. Confirme, pelo prefixo nos logs, que o tráfego migrou.
4. Só então revogue a antiga.

A ordem importa: revogar antes de publicar derruba o envio no intervalo. Rotacione periodicamente e sempre que alguém com acesso sair do time.

Se um segredo vazar

1. Revogue a chave imediatamente. Ela é o acesso, não o alerta.
2. Crie e publique uma nova.
3. Verifique o que foi enviado no período pelo prefixo comprometido.
4. Se houve envio indevido, avalie o impacto na qualidade do número.
5. Remova o segredo de onde ele vazou — inclusive do histórico do Git, onde apagar o arquivo não basta.

O passo 5 é o mais esquecido: um segredo comitado e depois removido continua acessível no histórico.

Além da chave

• Valide a assinatura dos webhooks — a chave protege a saída; a assinatura protege a entrada.
• Restrinja quem pode chamar a sua camada — não exponha um endpoint interno que envia WhatsApp sem autenticação própria.
• Registre quem disparou o quê — auditoria interna é o que responde "quem mandou essa mensagem?".

A validação de assinatura está detalhada em webhooks do WhatsApp.

Perguntas frequentes

Posso recuperar uma chave perdida?

Não. Só o hash fica salvo. Crie uma nova e revogue a antiga.

Quantas chaves posso ter?

Quantas fizerem sentido. Uma por consumidor é o desenho que permite revogar sem derrubar tudo.

Chave de API é a mesma coisa que token da Meta?

Não. A chave autentica você na camada do provedor; o token da Meta é usado por ele, do lado de lá, e não fica com você.

Preciso rotacionar mesmo sem vazamento?

Periodicamente, e obrigatoriamente quando alguém com acesso deixa o time.