Chaves de API em agentes de IA: onde guardar e como rotacionar

Chaves de API em agentes de IA: onde guardar e como rotacionar

Para gerenciar chaves de API de um agente de IA, guarde cada chave em um cofre de segredos, entregue-a apenas ao código que executa a ferramenta e nunca a coloque no prompt, no contexto do modelo ou nos logs. Cada credencial deve ter o menor escopo possível, pertencer a um único agente e ambiente, e poder ser trocada sem parar a operação. O modelo decide qual ação pedir. Quem detém a chave é a camada que executa.

Principais pontos

• O modelo nunca recebe a chave: ele pede uma ação, e uma camada de execução confiável anexa a credencial.
• Cofre de segredos ou variáveis injetadas em tempo de execução substituem arquivos, repositórios, planilhas e mensagens de chat.
• Uma chave por agente, por integração e por ambiente, com permissão mínima e, no início, só leitura sempre que possível.
• Rotação com período de sobreposição: criar a nova chave, validar, trocar, revogar a antiga e registrar tudo.
• Rotação imediata diante de suspeita de vazamento, saída de alguém com acesso ou mudança no escopo do agente.

Por que o modelo nunca deve ver a chave?

Tudo o que entra no contexto de um modelo de linguagem pode, em tese, sair dele. Se a chave está no prompt de sistema, em um documento recuperado ou no resultado de uma ferramenta, ela pode aparecer em uma resposta, em um log de conversa ou em uma chamada que um atacante conseguiu induzir. A injeção de prompt torna isso concreto: um texto malicioso dentro de um e-mail, de um PDF ou de uma mensagem de WhatsApp pode pedir ao agente que repita suas instruções ou envie dados para fora. O guia da OWASP sobre prevenção de injeção de prompt e a lista OWASP Top 10 para aplicações com LLM tratam essa classe de risco, incluindo a divulgação de informações sensíveis.

A regra de projeto é simples: o que o modelo não vê, ele não consegue vazar. Em vez de pedir ao modelo que monte uma requisição com cabeçalho de autorização, o modelo devolve uma intenção estruturada, por exemplo consultar_pedido com um número de pedido. Um código determinístico valida os parâmetros, busca a credencial no cofre, faz a chamada e devolve ao modelo apenas o resultado necessário. Essa separação é o mesmo princípio por trás do function calling: o modelo escolhe a ferramenta, o sistema executa.

Isso vale para qualquer arquitetura, seja um fluxo em n8n, um agente customizado ou um assistente de código. Em ferramentas de desenvolvimento, o mesmo cuidado aparece em permissões, sandbox e segredos, tema do artigo sobre segurança no Claude Code para empresas.

Onde guardar as chaves: do pior ao melhor lugar

A maioria dos vazamentos não vem de um ataque sofisticado. Vem de uma chave esquecida em um lugar cômodo. Use esta lista como guia de decisão, começando pelos lugares que devem ser eliminados.

• Prompt, instruções do agente ou arquivos de memória: nunca. É o pior lugar, porque coloca a chave diante do modelo.
• Repositório de código, mesmo privado, e arquivos de configuração versionados: evite. O histórico guarda a chave para sempre, e repositórios são clonados e compartilhados.
• Planilhas, documentos compartilhados, mensagens de chat e e-mail: proibido. São o canal mais comum de circulação informal de credenciais.
• Exportações de fluxos de automação: cuidado. Ao exportar um fluxo de uma plataforma de automação, confira se a credencial foi embutida no arquivo ou apenas referenciada.
• Variáveis de ambiente injetadas na hora da execução: aceitável como mínimo, desde que o ambiente seja restrito e as variáveis não sejam impressas em logs ou telas de diagnóstico.
• Cofre de segredos gerenciado (o do seu provedor de nuvem ou uma ferramenta dedicada): o destino recomendado. Oferece controle de acesso, trilha de auditoria e rotação centralizada.

Se a empresa ainda não tem cofre, o primeiro passo não precisa ser sofisticado. Escolha o recurso de segredos do provedor que já hospeda a aplicação, restrinja quem pode ler e comece por ali. O importante é que exista um único lugar de verdade, com dono definido.

Como limitar o escopo de cada credencial?

Guardar bem não basta se a chave pode fazer tudo. Se ela vazar, o dano é proporcional ao que ela permite. O princípio do menor privilégio, descrito no guia de autorização da OWASP, orienta essa decisão: conceda apenas o que a tarefa exige e nada além.

Na prática, aplique estas regras a cada integração do agente:

• Uma chave por agente. Se dois agentes compartilham uma credencial, você não consegue saber qual deles agiu nem revogar um sem derrubar o outro.
• Uma chave por ambiente. Teste e produção nunca usam a mesma credencial, e o ambiente de teste aponta para dados fictícios.
• Permissão de leitura primeiro. Um agente que consulta status de pedido não precisa de permissão para cancelar ou reembolsar.
• Escopos estreitos em OAuth. Quando a API oferece OAuth, peça somente os escopos necessários. A documentação de OAuth 2.0 do Google mostra como escopos delimitam o que o token autorizado pode acessar.
• Limites de uso e de gasto quando o provedor permite, para que uma chave comprometida não gere consumo ilimitado.
• Restrição de origem, como lista de IPs permitidos, quando a API oferece esse recurso.
• Tokens de curta duração em vez de chaves permanentes, sempre que a integração suportar.

Sistemas como ERP e CRM costumam ter perfis de permissão próprios. Antes de ligar um agente a eles, crie um usuário de serviço com perfil restrito, em vez de reaproveitar a chave de um administrador. Os riscos de cada caminho aparecem nos guias sobre integrar IA ao Bling, Omie ou Tiny e sobre integrar IA ao CRM.

Como rotacionar chaves sem derrubar o agente?

Rotacionar é trocar uma credencial por outra e invalidar a anterior. O risco operacional está no meio do caminho: se você revoga a chave antiga antes de o agente usar a nova, a operação para. Por isso a rotação segura usa um período de sobreposição, em que as duas chaves funcionam por um curto intervalo.

Um plano em etapas que serve para a maioria dos casos:

• Identifique o dono da credencial e todos os lugares que a usam: agentes, fluxos, scripts, ambientes. Se você não sabe onde ela é usada, a rotação vai quebrar algo.
• Crie a nova chave no provedor, com o mesmo escopo mínimo da anterior, e nunca com mais permissões por conveniência.
• Grave a nova chave no cofre como uma nova versão, sem apagar a antiga ainda.
• Faça o agente ler a nova versão. O ideal é que a camada de execução busque o segredo no cofre a cada início ou em intervalos curtos, em vez de ter o valor fixado no código.
• Valide com uma chamada de baixo risco, como uma consulta de leitura, e confira nos logs que a nova chave está em uso.
• Revogue a chave antiga no provedor.
• Registre a data, o motivo e o responsável pela troca, sem registrar o valor da chave.
• Confirme que nenhum erro de autenticação apareceu nas horas seguintes.

Defina também quando rotacionar. Há dois gatilhos. O primeiro é a rotação periódica, com um intervalo definido pela empresa conforme a sensibilidade da integração. O segundo é a rotação por evento: suspeita de vazamento, saída de uma pessoa que tinha acesso, fim de um fornecedor, mudança do que o agente pode fazer ou alerta do provedor. A rotação por evento deve ser ensaiada antes de existir um incidente, porque no dia da emergência ninguém quer descobrir que a chave está espalhada em cinco fluxos.

Como evitar que a chave vaze por logs, ferramentas e prompts?

Mesmo com cofre e escopo, a chave pode escapar por canais laterais. Revise estes pontos antes de colocar o agente em produção:

• Logs: nunca registre cabeçalhos de autorização, corpos de requisição com credenciais ou variáveis de ambiente completas. Aplique mascaramento automático em campos conhecidos.
• Mensagens de erro: o erro de uma API pode devolver a requisição inteira. Trate a resposta antes de enviá-la de volta ao modelo ou ao usuário.
• Resultados de ferramentas: devolva ao modelo só os campos necessários. Uma ferramenta que retorna a configuração completa de uma conta pode incluir segredos.
• Servidores MCP e extensões de terceiros: eles rodam com os acessos que você der. Avalie o que cada um lê antes de instalar, como descreve o guia sobre como auditar um servidor MCP.
• Detecção: use varredura automática de segredos no repositório e em pipelines, para pegar o erro humano antes que ele chegue ao ambiente.
• Camada de validação: confira o que o agente está prestes a enviar para fora. As práticas de guardrails de entrada, saída e ação ajudam a barrar uma resposta que contenha algo parecido com uma credencial.
• Gateways e painéis administrativos: se você usa uma plataforma de agentes com painel, trate o acesso a ele como acesso às chaves. O checklist de segurança do OpenClaw Gateway mostra o tipo de evidência a exigir antes de expor qualquer coisa.

Cenário ilustrativo: agente de pedidos no WhatsApp

Imagine, como exemplo hipotético, uma rede pequena de restaurantes com um agente no WhatsApp que responde dúvidas sobre cardápio e consulta o status de pedidos em um sistema de gestão. Este cenário é ilustrativo, não descreve um caso real.

No primeiro desenho, alguém colou a chave do sistema de gestão, que é de administrador, nas instruções do agente para que ele pudesse montar as chamadas sozinho. Qualquer cliente que conseguisse convencer o agente a repetir suas instruções teria acesso a essa chave, com permissão total.

No desenho corrigido, o agente só conhece duas ferramentas: consultar_status_pedido e buscar_cardapio. Uma camada de execução recebe o pedido do modelo, valida que o número tem o formato esperado, lê do cofre uma chave de um usuário de serviço com permissão apenas de leitura de pedidos e faz a chamada. O modelo recebe somente o status. A chave de teste é outra, e a de produção é rotacionada por um procedimento escrito, com sobreposição. Se um cliente tentar extrair a configuração, não há nada a extrair. Para o fluxo de conversa em si, vale ver o artigo sobre IA para restaurantes no WhatsApp.

Como o método mapear, limitar, pilotar e transferir se aplica

O trabalho com credenciais segue o mesmo método de qualquer projeto de agente. Em mapear, listamos cada integração, quem é o dono, onde a chave vive hoje e quais ações o agente realmente precisa executar. Em limitar, definimos escopo mínimo, uma chave por agente e ambiente, e o que o modelo pode ou não ver. Em pilotar, rodamos um fluxo real com logs e testamos a rotação ainda no piloto, incluindo a rotação de emergência, com uma métrica combinada de sucesso. Em transferir, entregamos o procedimento de rotação, o inventário de chaves e os responsáveis, para que a operação continue sem depender de quem implantou. A decisão final é expandir, ajustar ou parar.

Os dados que passam por essas integrações também importam. Se o agente toca em dados pessoais de clientes, a proteção das credenciais faz parte das medidas de segurança que a empresa precisa conseguir demonstrar. O artigo sobre LGPD e inteligência artificial detalha esse lado.

Perguntas frequentes

Posso colocar a chave de API no prompt se o agente for interno? Não é recomendável. Um agente interno também processa texto que não controlamos, como e-mails, anexos e páginas, e esse texto pode induzir o modelo a repetir o que está no contexto. Mantenha a chave na camada de execução e entregue ao modelo somente o resultado das ações.

Com que frequência devo rotacionar as chaves de um agente? Não há um intervalo universal. Defina um prazo periódico proporcional ao que a chave permite e à sensibilidade dos dados, e adicione gatilhos por evento, como suspeita de vazamento, saída de alguém com acesso ou troca de fornecedor. O mais importante é que a rotação seja um procedimento ensaiado e não uma improvisação.

Variáveis de ambiente bastam ou preciso de um cofre de segredos? Variáveis de ambiente injetadas em tempo de execução são um mínimo aceitável para começar, desde que o acesso ao ambiente seja restrito e nada as imprima em logs. Um cofre adiciona controle de acesso, histórico de uso e rotação centralizada, e passa a valer a pena assim que há mais de um agente ou mais de uma integração.

O que fazer se uma chave vazou? Revogue a chave imediatamente no provedor e crie uma nova com escopo mínimo, mesmo que isso cause uma pausa curta na operação. Depois, revise os logs do provedor para ver o que foi acessado no período, registre o incidente e descubra por qual canal o vazamento ocorreu para fechá-lo. Se houver dados pessoais envolvidos, avalie com o responsável por LGPD da empresa quais providências são necessárias.

Fontes

• OWASP: prevenção de injeção de prompt
• OWASP Top 10 para aplicações com LLM
• OWASP: guia de autorização
• Google: autorização OAuth 2.0