¿Qué son las variables de entorno y los secretos? Guía sencilla

Una variable de entorno es un ajuste con nombre —como DATABASE_URL o STRIPE_SECRET_KEY— que se entrega a tu app cuando se ejecuta, en lugar de escribirse en el código. Un secreto es una variable de entorno cuyo valor debe permanecer privado: una clave de API, una contraseña, una clave de firma. Mantener estos valores fuera del código te permite cambiarlos sin editar la app, usar valores distintos para las pruebas y para los clientes reales, y evitar que se filtren al compartir o publicar tu código.

Por qué importa cuando creas con IA

En cuanto tu app hace algo útil con otro servicio —cobra un pago, envía un email, llama a un modelo de IA— necesita una clave. Los creadores de apps con IA piden estas claves con frecuencia, y dónde acaba la clave decide si tu app está segura.

Hay dos cosas que suelen salir mal en las apps creadas con IA:

• La clave se pega en el chat o en el código. Entonces vive en el historial del chat, en los archivos del proyecto y en cualquier exportación o repositorio. Cualquiera que la vea puede usar tu cuenta.
• La clave se usa en el navegador. Si el código que llama a Stripe o a OpenAI se ejecuta en la página, la clave se envía a cada visitante. La gente mira, y los escáneres automáticos buscan claves expuestas constantemente.

Entender las variables de entorno te permite detectar ambos problemas y pedir la solución.

Una analogía cotidiana: la caja fuerte del hotel

El código de tu app es como la habitación del hotel. Los huéspedes (y los personal de limpieza, y cualquiera a quien des la tarjeta de acceso) entran en ella. No dejarías tu pasaporte encima de la mesa.

Las variables de entorno son la caja fuerte de la habitación. La habitación sabe que existe una caja fuerte y cómo abrirla cuando hace falta, pero el pasaporte no está tirado por ahí. Y si te cambias de habitación —de tu entorno de pruebas a tu web en vivo—, pones otro pasaporte en la caja fuerte de esa habitación, sin tener que redecorarla.

Cómo funciona

Tu código hace referencia a un nombre, no a un valor. En JavaScript en un servidor, eso se escribe como process.env.STRIPE_SECRET_KEY. Cuando la app arranca, la plataforma donde se ejecuta rellena el valor de ese nombre. Cambias el valor en los ajustes de la plataforma, reinicias o vuelves a desplegar, y la app usa el nuevo, sin cambiar el código.

De dónde salen los valores depende de dónde se ejecute la app:

Variables públicas frente a secretas

No todas las variables de entorno son secretas. Conviene separarlas en dos grupos:

Los frameworks web hacen esta división explícita. En Vite, solo se incluyen en el código del navegador las variables cuyo nombre empieza por VITE_; en Next.js, el prefijo es NEXT_PUBLIC_. Es una medida de seguridad: todo lo que lleva esos prefijos acaba en los archivos que descarga cada visitante, así que a un secreto nunca hay que ponerle uno de esos prefijos.

Un ejemplo práctico: un botón de resumen con IA

Quieres un botón «Resumir esta nota» que llame a un modelo de IA.

La versión insegura: el código del botón, ejecutándose en el navegador, llama directamente al proveedor de IA con la clave de API escrita dentro. Funciona en la vista previa. Pero también significa que cualquiera puede abrir las herramientas de desarrollo del navegador, copiar la clave y generar una factura en tu cuenta.

La versión segura:

1. Creas la clave en el proveedor de IA y la guardas como secreto llamado OPENAI_API_KEY (o similar) en los ajustes de tu proyecto.
2. El back end tiene una ruta, POST /api/summarise, que lee process.env.OPENAI_API_KEY, comprueba que el usuario ha iniciado sesión y llama al proveedor.
3. El botón llama a tu ruta, no al proveedor. El navegador nunca ve la clave.
4. Añades el mismo secreto a los ajustes de la app publicada y vuelves a desplegar, para que la web en vivo también lo tenga.

Ese patrón —el navegador llama a tu servidor, y tu servidor guarda la clave y llama al servicio— se aplica a pagos, email, mapas y cualquier otra API de pago. La guía para usar APIs de LLM cubre el caso de la IA con más profundidad.

Términos clave

• Archivo .env: un archivo de texto con líneas NOMBRE=valor que se usa en el desarrollo local. Añádelo a .gitignore para que no se suba a git.
• .env.example: una copia con los nombres pero sin valores reales, que se sube al repositorio para que los demás sepan qué variables configurar.
• Rotar: sustituir un secreto por uno nuevo y revocar el antiguo.
• Ámbito / permisos: muchos proveedores permiten crear claves que solo pueden hacer ciertas cosas. Una clave que solo puede enviar emails es menos peligrosa que una que puede hacerlo todo.
• Claves de prueba frente a claves reales: proveedores como Stripe dan claves separadas para las pruebas y para el dinero real. Usa las de prueba hasta el lanzamiento.
• Secreto de firma: un secreto que sirve para comprobar que un mensaje, como un webhook, realmente procede del remitente.

Errores habituales e ideas erróneas

• «Mi repositorio es privado, así que las claves dentro están bien». Los repositorios privados se comparten, se bifurcan, se exportan y se clonan en portátiles. Las claves no pertenecen ahí. Si conectas un proyecto a GitHub, comprueba que no se incluya ningún archivo .env.
• «Lo borré, así que ya no está». Git conserva el historial, y los registros del chat conservan los mensajes. Si una clave llegó a exponerse, rótala.
• Usar un prefijo público en un secreto. VITE_OPENAI_KEY pone tu clave en el paquete que descarga el navegador.
• Olvidar volver a desplegar. Cambiar una variable en los ajustes normalmente solo surte efecto después de reiniciar la app o volver a publicarla.
• Una sola clave para todo. Claves separadas para pruebas y para producción, y por app, permiten revocar una sin romper el resto.
• Sin límite de gasto. En las APIs de pago, establece un presupuesto o un límite en el panel del proveedor por si una clave se filtra.

Qué pedir a tu creador de apps con IA

• «Lee la clave secreta de Stripe desde una variable de entorno llamada STRIPE_SECRET_KEY. Úsala solo en el servidor.»
• «Asegúrate de que ningún secreto se use en código del cliente ni tenga un prefijo VITE_ / NEXT_PUBLIC_.»
• «Crea un .env.example que liste cada variable que necesita la app, sin valores, y asegúrate de que .env esté excluido de git.»
• «Revisa los archivos compilados del front end por si hay alguna cadena que parezca una clave de API.»

Nuestra lista de comprobación de seguridad para apps creadas con IA trata los secretos junto con el resto de comprobaciones que conviene hacer antes del lanzamiento.

Secretos en Mythex

En Mythex, los secretos son variables de entorno del proyecto que se inyectan tanto en el entorno de vista previa como en tu app publicada. Los añades en ajustes del proyecto → Secretos o con /secrets en el chat, y cuando el agente necesita una clave muestra una tarjeta de secretos en el chat, de modo que el valor se introduce en un campo del formulario y no queda en la transcripción de la conversación. Si cambias un secreto de una app en vivo, vuelve a publicar para que el despliegue lo recoja. Las exportaciones del proyecto no incluyen los secretos, y los archivos .env importados se eliminan para que los vuelvas a añadir en los ajustes. Consulta variables de entorno y secretos y secretos en el chat en la documentación.

Preguntas