Como Manter as Chaves de API Seguras na Sua App

Para manter as chaves de API seguras, guarde-as como segredos ou variáveis de ambiente no seu alojamento, use-as apenas em código do servidor e nunca as cole no chat, em ficheiros de código, em capturas de ecrã ou num repositório Git. Dê a cada chave a permissão mínima de que precisa, defina limites de gastos no fornecedor e, se uma chave vazar, rode-a — crie uma nova e elimine a antiga — em vez de a esconder apenas do sítio onde apareceu.

Uma chave de API é a palavra-passe de um serviço. A sua chave da OpenAI permite a alguém gastar o seu dinheiro em IA; a sua chave secreta da Stripe permite emitir reembolsos; a chave do seu fornecedor de e-mail permite enviar correio em seu nome. Os construtores de apps com IA são bons a ligar estas chaves, mas nem sempre são cuidadosos quanto ao sítio onde acabam, por isso este guia explica como as manter seguras e como verificar.

Chaves públicas e chaves secretas

Nem todas as chaves são secretas. Perceber a diferença evita que entre em pânico com a chave errada e ignore a certa.

Se não tiver a certeza do tipo de uma chave, consulte a documentação do fornecedor. Na dúvida, trate-a como secreta.

Passo 1: Guarde as chaves como segredos, não no código

As chaves pertencem às variáveis de ambiente ou às definições de segredos do seu alojamento. O seu código lê-as pelo nome em tempo de execução (por exemplo process.env.OPENAI_API_KEY), por isso o valor nunca aparece nos seus ficheiros. Para o contexto, veja o que são variáveis de ambiente e segredos.

Mova cada chave de API do código para variáveis de ambiente. Liste cada chave que encontrou, o ficheiro onde estava e o nome da variável que usou. Não mostre os valores.

Depois, confirme que não sobrou nada:

Procure em todo o projeto, incluindo ficheiros de configuração e quaisquer ficheiros .env, algo que pareça uma chave de API ou uma palavra-passe. Indique o ficheiro e a linha, não o valor.

Passo 2: Use chaves secretas apenas no servidor

Esta é a regra mais importante. Tudo o que o navegador recebe pode ser lido por um visitante — o código-fonte da página e os ficheiros JavaScript são visíveis nas ferramentas de programador.

Por isso, se a app precisar de chamar a OpenAI, o navegador deve chamar o seu servidor, e o servidor chama a OpenAI com a chave. A chave nunca sai do servidor.

A funcionalidade de chat chama a OpenAI diretamente a partir do navegador. Mova essa chamada para uma rota de API do servidor que lê OPENAI_API_KEY do ambiente. O navegador deve chamar apenas a nossa rota. Exija início de sessão para a rota.

Fique atento a uma armadilha comum nas frameworks de frontend: as variáveis com um prefixo público — VITE_ no Vite, NEXT_PUBLIC_ no Next.js — são incluídas de propósito no código do navegador. Uma chave secreta com um desses prefixos fica exposta, mesmo estando "numa variável de ambiente".

Passo 3: Teste que nada vaza

Não parta do princípio de que funcionou — verifique o site em produção:

1. Abra a app publicada num navegador.
2. Abra as ferramentas de programador e o separador Sources ou Network.
3. Procure nos ficheiros os primeiros caracteres de cada chave secreta (por exemplo sk_ ou sk-).
4. Verifique os pedidos de rede que a app faz. Um pedido que vai diretamente do navegador para um fornecedor de IA pago é um sinal de alarme.

Se encontrar uma chave secreta, mova-a para o servidor (passo 2) e rode-a (passo 6), porque já estava pública.

Passo 4: Restrinja o que cada chave pode fazer

Muitos fornecedores permitem limitar uma chave:

• Chaves com âmbito ou restritas que só podem fazer o que a sua app precisa. A Stripe, por exemplo, suporta chaves restritas com permissões específicas.
• Restrições por domínio ou por IP para chaves que têm de ser públicas, como as de mapas.
• Chaves separadas por app e por ambiente, para que uma fuga não exponha tudo e revogar uma não afete as outras.
• Chaves de teste durante a construção, e chaves reais apenas na app publicada.

Passo 5: Ponha um teto nos danos

Mesmo uma chave bem protegida pode ser mal usada através da própria app — por exemplo, alguém a automatizar a sua funcionalidade de IA milhares de vezes.

• Defina limites ou alertas de gastos em todos os fornecedores pagos.
• Exija início de sessão para qualquer funcionalidade que custe dinheiro por cada chamada.
• Acrescente um limite de utilização por utilizador. Veja o que é o limite de pedidos (rate limiting).

Acrescente um limite de 30 pedidos de IA por utilizador por hora em /api/chat. Devolva uma mensagem clara quando o limite for atingido. Rejeite pedidos de utilizadores que não tenham sessão iniciada.

Passo 6: Rode as chaves que vazarem

Se uma chave secreta aparecer num sítio onde não devia — uma mensagem de chat, um commit, uma captura de ecrã, um pedido de suporte, código do navegador — assuma que está comprometida.

1. Crie uma nova chave no fornecedor.
2. Atualize o segredo nas definições da sua app.
3. Volte a publicar ou a fazer deploy para que a app em produção use a nova chave.
4. Elimine a chave antiga no fornecedor.
5. Verifique os registos de utilização do fornecedor para atividade que não reconheça.

Apagar a mensagem do chat ou o commit do Git não basta. O histórico do Git guarda versões antigas, e tudo o que esteve público pode já ter sido copiado.

Erros comuns

• Colar uma chave no prompt. Fica no histórico do chat. Use antes um formulário de segredos.
• Um prefixo público numa variável secreta. VITE_OPENAI_API_KEY envia a chave a todos os visitantes.
• Enviar um ficheiro .env para o repositório. Confirme que está no .gitignore antes do primeiro push.
• Uma chave para tudo. Use chaves separadas para teste e produção, e para cada app.
• Sem limite de gastos. Uma chave exposta ou abusada sem teto pode gerar uma fatura grande antes de dar por isso.
• Esconder em vez de rodar. Depois de uma chave ser exposta, só uma nova chave a corrige.
• Chaves em capturas de ecrã. Corte ou desfoque as páginas de definições antes de as partilhar para pedir ajuda.

Lista de verificação

• Cada chave está guardada como segredo ou variável de ambiente, não no código.
• Nenhum ficheiro .env ou chave está enviado para o Git.
• As chaves secretas são usadas apenas em código do servidor.
• Nenhuma variável secreta usa um prefixo público como VITE_ ou NEXT_PUBLIC_.
• Procurei no JavaScript do site em produção o prefixo de cada chave e não encontrei nada.
• As chaves têm âmbito ou são restritas sempre que o fornecedor o permite.
• As chaves de teste e as reais estão separadas.
• As funcionalidades pagas exigem início de sessão e têm limites por utilizador.
• Cada fornecedor pago tem um limite ou alerta de gastos.
• Sei como rodar cada chave, e qualquer chave que alguma vez tenha estado exposta foi rodada.

Manter as chaves seguras na Mythex

A Mythex mantém as chaves fora do seu código e do chat de duas formas:

• Cartão de pedido de segredos. Quando o agente precisa de uma chave, mostra um cartão no chat onde introduz o valor em campos de formulário, e não na caixa de mensagens, e fica guardado como segredo do projeto. Veja Segredos no chat.
• Definições do projeto → Segredos, ou /secrets no chat, para adicionar ou alterar chaves por si próprio. Veja Variáveis de ambiente e segredos.

Depois de alterar um segredo de uma app publicada, publique novamente para que a app em produção o use. Os projetos exportados não incluem os segredos, por isso volte a adicioná-los sempre que executar o código noutro sítio. Se uma chave alguma vez aparecer no chat, rode-a no fornecedor.

Para o resto da verificação de segurança antes do lançamento, percorra a lista de verificação de segurança para apps criadas com IA. Se estiver a acrescentar funcionalidades de IA, como usar APIs de LLM explica chaves e custos com mais profundidade.

Perguntas