Armazene uma chave de API com segurança: variável de ambiente, .gitignore, correção de vazamento

Mantenha a chave em uma variável de ambiente, não no seu código, e mantenha qualquer arquivo .env fora do git com uma linha no .gitignore. Se uma chave já acabou em algum lugar público, resolva a chave primeiro e arrume o resto depois: limpar o histórico do git enquanto a chave ainda está no seu código e nas suas ferramentas não resolve nada.

É essa a ideia toda. Este guia é a versão prática (o básico está em O que é uma chave de API): três comandos, uma requisição funcionando e um plano curto para o dia ruim.

Por que a chave não pertence ao seu código#

Uma chave de API é uma senha que gasta o seu dinheiro. Qualquer pessoa que a tenha pode enviar requisições na sua conta, e o serviço não consegue diferenciá-la de você.

O jeito habitual de dar errado é entediante. Você cola a chave num script para fazer a primeira requisição funcionar, o script funciona, você faz git push, e o repositório é público. Ou você envia seu arquivo de configuração para um colega. Ou tira um print de um erro com a chave visível no canto. O resultado é o mesmo todas as vezes.

O GitHub conhece bem esse padrão. A verificação de segredos dele (documentação do GitHub, consultada em 29 de outubro de 2026) percorre todo o histórico do Git em todos os branches em busca de credenciais embutidas no código, e também issues, pull requests, discussões, wikis e gists secretos, e gera um alerta quando encontra uma. O que significa que apagar a linha no próximo commit não muda nada: o commit antigo ainda a tem.

Aqui está o mesmo script antes e depois.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key="<your-key>",  # pasted here: ends up in git
)

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

A segunda versão pode ir para o GitHub, um chat ou uma revisão de código como está. A chave fica na sua máquina, fora do arquivo.

Passo 1: coloque a chave em uma variável de ambiente#

Uma variável de ambiente é um valor nomeado que o seu terminal entrega a todo programa que ele inicia. O script pede CHEAPTOKENS_API_KEY pelo nome e nunca vê de onde ela veio.

No macOS e Linux:

export CHEAPTOKENS_API_KEY="<your-key>"

No Windows PowerShell:

setx CHEAPTOKENS_API_KEY "<your-key>"

Dois detalhes pegam as pessoas. export dura apenas para aquela janela do terminal, então para mantê-la, adicione a linha ao seu perfil do shell (~/.zshrc ou ~/.bashrc). E setx não altera a janela em que você digitou: abra um novo terminal antes de testar.

Agora uma requisição completa. Ela usa o endpoint compatível com OpenAI, https://api.cheaptokens.dev/v1, e o DeepSeek-V4-Flash com seu id completo (deepseek-ai/DeepSeek-V4-Flash-0731; pegue os ids na documentação do CheapTokens, já que os nomes diferem entre provedores):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

Uma saudação curta é uma requisição de aproximadamente 20 tokens de entrada e 20 de saída, o que nos preços atuais dá $0.0000023 (a lista completa está na página de preços). Se você ainda não enviou uma primeira requisição, Sua primeira requisição de API com o CheapTokens explica do zero.

A resposta do modelo volta em choices[0].message.content, e usage mostra os tokens contados. A chave nunca aparece no arquivo.

Passo 2: use um arquivo .env sem commitá-lo#

Digitar export em cada nova janela cansa. Um arquivo .env mantém o valor em um só lugar, ao lado do projeto:

CHEAPTOKENS_API_KEY=<your-key>

O Python o lê com python-dotenv (pip install python-dotenv):

from dotenv import load_dotenv
load_dotenv()  # fills os.environ from .env

O arquivo só é seguro se o git nunca o vir. Adicione-o ao .gitignore antes do primeiro commit:

echo ".env" >> .gitignore
git check-ignore -v .env

Se tudo estiver certo, o segundo comando imprime algo como .gitignore:1:.env .env: o git informa qual regra está ignorando o arquivo. Se não imprimir nada, a regra não está funcionando. No Windows, crie .gitignore em um editor com uma linha .env, ou use Add-Content .gitignore .env: o >> do PowerShell pode gravar em UTF-16, que o git pode ignorar.

Uma armadilha: .gitignore só afeta arquivos que o git ainda não está rastreando. Se .env já foi commitado uma vez, execute git rm --cached .env para que o git pare de rastreá-lo, e trate a chave dentro dele como exposta (mais sobre isso abaixo). Um hábito organizado é commitar um .env.example com o nome da variável e um placeholder em vez do valor, para que um colega saiba o que definir.

Se a chave vazou: o que fazer, em ordem#

Talvez a chave tenha ido para um repositório público, talvez estivesse num print, talvez você tenha colado a configuração inteira num tópico de fórum. A ordem importa mais do que a velocidade de qualquer passo isolado.

A orientação do próprio GitHub (mesma página, consultada em 29 de outubro de 2026) é revogar a credencial imediatamente; reescrever o histórico do Git é opcional e muitas vezes desnecessário depois que a credencial é revogada. As pessoas tendem a fazer o contrário: passam uma hora limpando o histórico enquanto a chave ainda funciona. Não faça isso.

Depois da limpeza, envie uma pequena requisição de teste, como no Passo 1, e verifique seu saldo. Se ela responder e o saldo e as requisições parecerem normais, a limpeza terminou; fique de olho no saldo nos próximos dias. Uma chave que foi pública deve ser tratada como exposta mesmo depois de você removê-la do código, então observe o saldo e a contagem de requisições em busca de algo que você não enviou, e não reutilize essa chave em novos lugares. Para os lugares onde uma chave costuma ficar, veja Onde colocar sua própria chave de API.

Teste você mesmo#