A API Key autoriza chamadas à sua API de WhatsApp. Trate-a como uma senha de serviço: quem obtém a chave pode tentar executar operações permitidas àquele token. O painel do StackZap Cloud mostra credenciais específicas por ambiente; proteja cada uma com o mesmo cuidado.
- 01Guarde a chave em secret manager
- 02Leia-a no servidor em runtime
- 03Oculte-a de logs e respostas
- 04Troque-a se houver exposição
Boas práticas para a aplicação
- Injete a credencial no backend por variável de ambiente ou cofre de secrets.
- Não inclua a chave em código JavaScript executado no navegador ou em app cliente distribuído.
- Restrinja acesso ao repositório, pipeline de deploy e painel que armazena secrets.
- Masque valores de
X-API-Keyem logs, traces, relatórios e gravações de tela. - Use ambientes e credenciais diferentes para desenvolvimento e produção quando possível.
Se a chave aparecer em público
Remova o valor do local exposto, mas considere que apagar o texto não invalida cópias já feitas. Siga a função de revogação ou rotação disponível para seu ambiente. Se não encontrar a opção ou suspeitar de acesso indevido, procure o suporte com o identificador do ambiente, sem enviar a chave antiga em texto aberto.
Confira os mecanismos de autenticação aceitos na documentação da StackZap. Para as instruções do seu ambiente Cloud, entre em contas.stacklab.digital e consulte o painel correspondente.
Por que a API Key precisa ficar no servidor
Uma página web é entregue ao navegador do visitante. Tudo que chega no código JavaScript pode ser inspecionado, inclusive valores incluídos no bundle, variáveis de build e chamadas de rede. Ofuscação não transforma uma chave embutida em segredo. Se o navegador precisa iniciar uma ação, envie uma solicitação ao seu backend autenticado; o backend valida o usuário e os parâmetros e então chama a StackZap com a credencial guardada no servidor.
O mesmo princípio vale para aplicativos móveis distribuídos, extensões, scripts compartilhados e automações de terceiros: o usuário final pode extrair valores do pacote ou do processo. Se um agente de IA utiliza a integração, não entregue a chave no prompt ou contexto. Crie uma ferramenta no backend com operações limitadas e validações explícitas.
Use um cofre de segredos
Em desenvolvimento, mantenha arquivo de ambiente fora do Git e inclua um modelo sem valores reais para orientar a equipe. Em produção, prefira o secret manager da plataforma. Dê acesso apenas ao serviço que precisa da API Key e a operadores responsáveis. Não reutilize a mesma credencial em todos os projetos, clientes ou estágios.
Se usar variável de ambiente, considere quem pode ler a configuração do processo, dumps e diagnósticos. Não imprima todas as variáveis para investigar um problema. Em pipeline CI/CD, limite quem pode editar workflow e consultar secrets, proteja branches de produção e reveja permissões de deploy. Uma pessoa que altera código e acessa a chave pode conseguir incluí-la num artefato público.
Segmente ambientes e acessos
Use credenciais distintas para desenvolvimento, homologação e produção sempre que o mecanismo disponível permitir. A URL e a chave devem pertencer ao mesmo ambiente. Isso reduz o impacto de um teste mal configurado e facilita revogar acesso de um sistema sem interromper todos os demais. Nomeie a variável por ambiente, sem colocar o valor no nome ou no log.
Defina responsáveis: quem solicita, aprova, provisiona, rotaciona e revoga a credencial. A revisão deve ocorrer quando alguém muda de função ou deixa a equipe, quando um serviço é aposentado e após qualquer suspeita de exposição. A lista de acessos precisa estar atualizada, não apenas documentada no onboarding.
Evite vazamentos indiretos
Um segredo pode aparecer em mais lugares do que o arquivo-fonte: saída de terminal, captura de tela, tickets, gravação de sessão, erro de framework, trace HTTP, log do proxy, relatório de bug e histórico do shell. Configure redaction para X-API-Key e revise ferramentas de observabilidade. Em exemplos, use placeholders claramente fictícios e não copie um comando completo com valor real para uma página de documentação pública.
Não envie a chave como query string. URLs podem ser gravadas em histórico, proxy e analytics. Não a coloque no campo de usuário do banco, em nome de instância ou em tags de monitoramento. Evite registrar headers completos. Ao compartilhar um diagnóstico, substitua o valor por [redigida] antes de anexar.
O que fazer se a chave vazar
Considere comprometida qualquer credencial publicada em repositório, compartilhada com destinatário errado ou incluída num artefato acessível. Remover a linha não invalida cópias, forks, logs ou commits. Avalie se houve chamadas anormais, revogue ou rotacione conforme o procedimento disponível e atualize os serviços dependentes. Se não encontrar a ação no painel, contate suporte informando apenas o ambiente e horário aproximado.
Depois da troca, verifique se nenhum serviço continua usando a chave antiga e retire cópias de locais públicos. Reveja o caminho que causou a exposição: segredo em bundle, permissão excessiva, pipeline ou logging. Se houve uso indevido, preserve evidências necessárias e siga seu plano de resposta a incidentes. Não publique o valor novamente para pedir ajuda.
Rotação sem interrupção desnecessária
Planeje a rotação considerando quais aplicações dependem da credencial. Prepare a configuração nova, implante num serviço de cada vez e valide uma chamada não destrutiva ou uma consulta. Só então invalide a chave anterior quando o mecanismo do produto permitir. Se apenas uma chave puder existir por vez, escolha janela de menor atividade, comunique operadores e tenha plano de retorno. Não deixe credenciais antigas ativas sem prazo.
Checklist de proteção
- A credencial nunca é enviada ao navegador ou aplicativo cliente.
- Segredos ficam fora do repositório e de artefatos públicos.
- Acesso ao cofre e ao pipeline segue menor privilégio.
- Produção e homologação usam configuração separada.
- Logs, traces e relatórios mascaram
X-API-Key. - Rotação e revogação têm responsáveis definidos.
- Um vazamento aciona investigação e troca, não apenas exclusão do texto.
- Agentes e automações usam operações limitadas no backend.
Arquitetura simples para integração web
O navegador envia ao seu backend uma intenção, por exemplo “consultar status desta instância”. O backend autentica o usuário, verifica se ele pode acessar aquele recurso e monta a chamada StackZap usando a API Key guardada no servidor. A resposta é filtrada para retornar apenas os dados necessários à interface. Esse padrão evita entregar a credencial ao navegador e dá um ponto central para registrar auditoria e limitar operações.
Não crie um proxy genérico que aceite URL e método arbitrários enviados pelo cliente. Isso pode transformar seu servidor num relay para qualquer rota e ampliar o impacto de uma conta comprometida. Crie funções específicas como consultarStatus ou enviarNotificacao, valide cada parâmetro e permita apenas IDs autorizados. Exija autorização no servidor em cada chamada; esconder um botão no frontend não é controle de acesso.
Segredos em containers e tarefas automatizadas
Ao executar containers, injete secrets usando o mecanismo apropriado à plataforma e restrinja quem pode inspecionar configuração e processos. Variáveis de ambiente são melhores do que gravar a chave na imagem, mas ainda podem aparecer em dumps ou ferramentas administrativas. Não use argumentos de linha de comando com o valor literal, pois podem ficar em histórico e lista de processos.
Em jobs agendados, limite quais tarefas recebem a credencial e evite imprimir o ambiente inteiro ao iniciar. Em forks de repositórios e ambientes de preview, não disponibilize chave de produção. Uma contribuição de código de terceiro não deve executar num ambiente que tem secrets de produção até ser revisada.
Controle de acesso e auditoria
Revise quem pode consultar o painel do ambiente, alterar variáveis, iniciar deploy e ler logs. Essas permissões podem dar acesso indireto à credencial, mesmo que a pessoa não veja o campo diretamente. Registre mudanças de configuração e autoria sem registrar o valor. Para aplicações multi-tenant, associe o acesso à instância ao usuário e ao tenant em cada request.
Defina um processo de desligamento de integração: pare workers, remova o secret do runtime, revogue a credencial conforme mecanismo do ambiente e registre a data. Faça inventário de cópias em pipeline, ambiente de desenvolvimento e ferramentas de monitoramento. Apagar o secret da configuração atual não o remove de um dump antigo.
Responda a um alerta de uso anormal
Se notar chamadas inesperadas, proteja primeiro o ambiente e reduza o acesso à credencial. Registre horários e endpoints afetados, preserve os logs necessários e avalie se dados de contatos foram expostos. Revogue ou troque a chave conforme orientação disponível, atualize os serviços legítimos e monitore se o padrão anormal cessou. Comunique responsáveis internos segundo seu plano de incidente.
Peça suporte sem mandar a API Key. Informe ambiente, janela de tempo, operação e identificadores de requisição. Uma chave nunca deve ser compartilhada para “validar” titularidade. Depois da contenção, revise permissões, logs e origem do vazamento e inclua prevenção no processo de deploy.
Faça uma revisão de exposição periódica
Pesquise repositórios e projetos por padrões de credenciais, sem imprimir valores encontrados nos relatórios. Use secret scanning no fluxo de desenvolvimento e bloqueie commits que incluam segredos conhecidos. A ferramenta reduz erros acidentais, mas não substitui revisão de logs, screenshots e ambientes. Depois de um alerta, encaminhe o achado a um responsável e remova o acesso conforme o processo definido.
Inclua pipelines, sites de documentação, ferramentas de monitoramento e ambientes de preview na revisão. Secrets não devem ser enviados para builds públicos nem compartilhados automaticamente com forks. Revise quem pode baixar artefatos, editar workflows e ver logs de deploy; essas permissões frequentemente dão acesso indireto ao valor.
Use placeholders seguros na documentação
Nos exemplos, escreva ${STACKZAP_API_KEY} ou [SUA_API_KEY], nunca um valor aparentemente válido. Explique que a variável deve ser carregada no servidor e não no frontend. Evite comandos que incentivem colar a chave no terminal, no prompt de IA ou no navegador. Uma documentação segura torna o caminho correto mais fácil que o inseguro.
Se precisar produzir uma captura de tela para suporte, use conta de teste ou oculte o valor antes de gravar. Um blur pode ser desfeito dependendo do arquivo; prefira remover o dado antes da captura. Não envie logs brutos para ferramentas externas sem redaction e autorização.
Formalize o ciclo de vida do segredo
Para cada API Key, registre identificador da credencial, serviço que a usa, ambiente, responsável, data de criação e última revisão. Não registre o valor. Na desativação, remova configuração de todos os ambientes, revogue pelo mecanismo disponível e confirme que o serviço deixou de usar a chave. Esse inventário torna rotação e resposta a incidente mais rápidas.
Confira quem pode alterar o backend
Uma chave guardada no servidor ainda pode ser exposta se um usuário consegue alterar o código que a utiliza ou ler traces detalhados. Proteja branches, revise alterações no cliente HTTP e limite acesso a logs e dumps. A revisão de segurança deve incluir quem pode alterar uma rota que usa a API Key, não apenas quem pode abrir o secret manager.
Se uma aplicação permite que usuários configurem endpoints, restrinja quais destinos podem ser chamados e como a credencial é associada. Nunca aceite que um usuário escolha uma URL qualquer e faça o backend enviar X-API-Key para ela. Isso pode encaminhar o segredo a um servidor controlado por terceiro.
Adicione uma revisão de segurança quando incluir integração, endpoint ou worker que usa a chave. Confirme se a operação é necessária, se o acesso pode ser menor e se os logs continuam mascarados. Revisar esse caminho reduz o risco de uma credencial antiga ganhar usos que ninguém acompanha.
Inclua a chave no inventário de ativos
Relacione cada credencial ao serviço e ao ambiente que a utiliza, com responsável e data de revisão. Ao criar uma integração nova, confirme que ela precisa de acesso direto ou pode chamar um backend existente. Essa decisão reduz o número de cópias e facilita revogação. Se não puder identificar quem mantém uma chave antiga, investigue seus usos antes de removê-la para não interromper uma operação legítima.
Para revisar uma exposição, inclua a data do achado, o local, o alcance potencial e a ação de rotação. Não copie o segredo para o relatório; use o identificador da credencial. A nota permite confirmar a resolução sem criar outra cópia da informação sensível.