Guardar una API key de forma segura: variable de entorno, .gitignore, arreglo de filtraciones

Mantén la clave en una variable de entorno, no en tu código, y mantén cualquier archivo .env fuera de git con una línea en .gitignore. Si una clave ya ha acabado en algún lugar público, ocúpate primero de la clave y ordena después: limpiar el historial de git mientras la clave sigue en tu código y tus herramientas no arregla nada.

Esa es toda la idea. Esta guía es la versión práctica (lo básico está en Qué es una API key): tres comandos, una petición que funciona y un plan breve para el día malo.

Por qué la clave no pertenece a tu código#

Una API key es una contraseña que gasta tu dinero. Cualquiera que la tenga puede enviar peticiones con tu saldo, y el servicio no puede distinguirlos de ti.

La forma habitual en que sale mal es aburrida. Pegas la clave en un script para que la primera petición funcione, el script funciona, haces git push y el repositorio es público. O le envías tu archivo de configuración a un colega. O haces una captura de pantalla de un error con la clave visible en la esquina. El mismo resultado cada vez.

GitHub conoce bien este patrón. Su escaneo de secretos (GitHub docs, consultado el 29 de octubre de 2026) revisa todo el historial de Git en todas las ramas en busca de credenciales codificadas directamente, y también issues, pull requests, discusiones, wikis y gists secretos, y lanza una alerta cuando encuentra una. Lo que significa que borrar la línea en tu siguiente commit no cambia nada: el commit antiguo todavía la tiene.

Aquí está el mismo script antes y después.

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"],
)

La segunda versión puede ir a GitHub, a un chat o a una revisión de código tal cual. La clave vive en tu máquina, fuera del archivo.

Paso 1: pon la clave en una variable de entorno#

Una variable de entorno es un valor con nombre que tu terminal entrega a cada programa que inicia. El script pide CHEAPTOKENS_API_KEY por su nombre y nunca ve de dónde vino.

En macOS y Linux:

export CHEAPTOKENS_API_KEY="<your-key>"

En Windows PowerShell:

setx CHEAPTOKENS_API_KEY "<your-key>"

Dos detalles despistan a la gente. export solo dura para esa ventana de terminal, así que para conservarla, añade la línea a tu perfil de shell (~/.zshrc o ~/.bashrc). Y setx no cambia la ventana en la que lo escribiste: abre un terminal nuevo antes de probar.

Ahora una petición completa. Usa el endpoint compatible con OpenAI, https://api.cheaptokens.dev/v1, y DeepSeek-V4-Flash con su id completo (deepseek-ai/DeepSeek-V4-Flash-0731; toma los ids de la documentación de CheapTokens, ya que los nombres difieren entre proveedores):

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)

Un saludo corto es una petición de aproximadamente 20 tokens de entrada y 20 de salida, que a los precios actuales es $0.0000023 (la lista completa está en la página de precios). Si aún no has enviado una primera petición, Tu primera petición a la API con CheapTokens lo explica desde cero.

La respuesta del modelo vuelve en choices[0].message.content, y usage muestra los tokens que contó. La clave nunca aparece en el archivo.

Paso 2: usa un archivo .env sin hacer commit de él#

Escribir export en cada ventana nueva cansa. Un archivo .env mantiene el valor en un solo lugar, junto al proyecto:

CHEAPTOKENS_API_KEY=<your-key>

Python lo lee con python-dotenv (pip install python-dotenv):

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

El archivo solo es seguro si git nunca lo ve. Añádelo a .gitignore antes del primer commit:

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

Si todo está bien, el segundo comando imprime algo como .gitignore:1:.env .env: git te dice qué regla está ignorando el archivo. Si no imprime nada, la regla no funciona. En Windows, crea .gitignore en un editor con una línea .env, o usa Add-Content .gitignore .env: el >> de PowerShell puede escribir UTF-16, que git puede ignorar.

Una trampa: .gitignore solo afecta a archivos que git aún no está rastreando. Si .env ya se hizo commit una vez, ejecuta git rm --cached .env para que git deje de rastrearlo, y trata la clave que contiene como expuesta (más sobre esto abajo). Un hábito ordenado es hacer commit de un .env.example con el nombre de la variable y un marcador de posición en lugar del valor, para que un compañero sepa qué configurar.

Si la clave se filtró: qué hacer, en orden#

Quizá la clave fue a un repositorio público, quizá estaba en una captura de pantalla, quizá pegaste toda la configuración en un hilo de un foro. El orden importa más que la velocidad de cualquier paso individual.

La propia guía de GitHub (misma página, consultada el 29 de octubre de 2026) es rotar la credencial de inmediato; reescribir el historial de Git es opcional y a menudo innecesario una vez revocada la credencial. La gente tiende a hacerlo al revés: pasan una hora limpiando el historial mientras la clave sigue funcionando. No lo hagas.

Después de la limpieza, envía una pequeña petición de prueba, como en el Paso 1, y revisa tu saldo. Si responde y el saldo y las peticiones parecen normales, la limpieza ha terminado; vigila el saldo durante los próximos días. Una clave que ha sido pública debe tratarse como expuesta incluso después de quitarla del código, así que vigila el saldo y el recuento de peticiones en busca de algo que no enviaste, y no reutilices esa clave en lugares nuevos. Para los lugares donde suele vivir una clave, consulta Dónde conectar tu propia API key.

Compruébalo tú mismo#