¿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. Guardar estos valores fuera del código te permite cambiarlos sin editar la app, usar unos distintos para las pruebas y para los clientes reales, y evitar que se filtren cuando compartes o publicas tu código.

Por qué importa cuando construyes con IA

En cuanto tu app hace algo útil con otro servicio —cobrar un pago, enviar un correo, llamar a un modelo de IA— necesita una clave. Los creadores de apps con IA piden estas claves con frecuencia, y el lugar donde acaba la clave decide si tu app es segura.

En las apps creadas con IA suelen fallar dos cosas:

• La clave se pega en el chat o en el código. Entonces queda en el historial del chat, en los archivos del proyecto y en cualquier exportación o repositorio. Quien la vea puede usar tu cuenta.
• La clave se usa en el navegador. Si el código que llama a Stripe u OpenAI se ejecuta en la página, la clave llega a todos los visitantes. La gente sí 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 las personas de limpieza, y cualquiera a quien des la tarjeta de acceso) pasan por ella. No dejarías el pasaporte encima de la mesa.

Las variables de entorno son la caja fuerte de la habitación. La habitación sabe que hay 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 sitio real—, 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 ve como process.env.STRIPE_SECRET_KEY. Cuando arranca la app, la plataforma en la que se ejecuta rellena el valor de ese nombre. Cambias el valor en los ajustes de la plataforma, reinicias o vuelves a publicar, y la app usa el nuevo, sin cambiar 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 explícita esta división. En Vite, solo las variables cuyo nombre empieza por VITE_ se incluyen en el código del navegador; en Next.js, el prefijo es NEXT_PUBLIC_. Es una medida de seguridad: todo lo que tiene esos prefijos acaba en los archivos que descarga cada visitante, así que a un secreto nunca se le debe poner uno de ellos.

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 backend 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 publicar, para que el sitio 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 los pagos, al correo, a los mapas y a cualquier otra API de pago. La guía para usar APIs de LLM explica el caso de la IA con más detalle.

Términos clave

• Archivo .env: un archivo de texto con líneas NOMBRE=valor que se usa en el desarrollo local. Inclúyelo en .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 otro nuevo y revocar el antiguo.
• Ámbito / permisos: muchos proveedores permiten crear claves que solo pueden hacer ciertas cosas. Una clave que solo puede enviar correos 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 que lances la app.
• Secreto de firma: un secreto que sirve para comprobar que un mensaje, como un webhook, viene realmente del remitente.

Errores comunes e ideas equivocadas

• «Mi repositorio es privado, así que las claves en él están bien». Los repositorios privados se comparten, se hacen fork, 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 guarda el historial, y los chats guardan los mensajes. Si una clave llegó a estar expuesta, rótala.
• Usar un prefijo público en un secreto. VITE_OPENAI_KEY pone tu clave en el código del navegador.
• Olvidar volver a publicar. Cambiar una variable en los ajustes normalmente solo surte efecto cuando la app se reinicia o se vuelve a publicar.
• Una sola clave para todo. Tener claves separadas para pruebas y para producción, y por app, permite revocar una sin romper las demás.
• Sin límite de gasto. En las APIs de pago, configura un presupuesto o un límite en el panel del proveedor por si una clave se filtra.

Qué pedirle a tu creador con IA

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

Nuestra lista de comprobación de seguridad para apps creadas con IA cubre los secretos junto con las demás comprobaciones que conviene hacer antes de lanzar.

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, para que el valor se introduzca en un campo del formulario y no quede 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, así que tendrás que volver a añadirlos en los ajustes. Consulta variables de entorno y secretos y secretos en el chat en la documentación.

Preguntas