Variables de entorno para claves de API explicadas para creadores no técnicos: mantén las claves fuera de prompts y repositorios, mapea dev/staging/prod y rótalas de forma segura.
Una clave API es como una contraseña para un servicio con el que tu app habla (pagos, correo, mapas, IA, analítica). Le dice a ese servicio: "esta petición viene de mi cuenta", para que el servicio pueda cobrarte, aplicar límites y permitir acceso.
Las claves se filtran porque a menudo empiezan como un copia-y-pega rápido. Lo pegas en un chat, en un archivo de configuración o en una nota "solo por ahora", y luego queda guardado en un lugar que no querías compartir.
Las vías comunes de filtración accidental incluyen prompts de chat (especialmente cuando estás construyendo rápido en una herramienta de vibe-coding), commitear una clave a un repo o subir un zip "para revisión", poner una clave en una captura de pantalla o grabación, dejarla en un doc o chat de equipo compartido, o hardcodearla en código front-end que cualquier navegador puede leer.
El riesgo no es abstracto. El dolor más rápido son las facturas sorpresa: alguien usa tu clave para llamar a una API miles de veces. El siguiente riesgo es el acceso a datos: si la clave puede leer datos de clientes o enviar correos, un atacante puede hacer lo mismo. En el peor caso, una clave con permisos amplios puede llevar a la toma de la cuenta (por ejemplo, si puede crear nuevas claves).
No necesitas ser un experto en seguridad para obtener la mayor parte del beneficio. Un pequeño cambio de hábito ayuda mucho: trata las claves como "secretos" y mantenlas fuera de prompts y repos. Eso es exactamente para lo que sirven las variables de entorno: guarda el secreto en un lugar protegido y deja que tu app lo lea en tiempo de ejecución, sin incrustarlo en el código o en capturas.
Si recuerdas una regla, usa esta: código es lo que hace tu app, configuración es cómo se comporta, y secretos es lo que nunca debe revelar.
Código es la lógica que construyes y entregas (pantallas, botones, cálculos, llamadas a APIs). Debe ser seguro para compartir con compañeros y a menudo acaba en un repo.
Configuración son ajustes que pueden ser públicos sin causar daño. Piensa: el nombre de tu app, en qué región correr, feature flags o la URL base de un servicio. Si alguien lo ve, no debería poder gastarte dinero, acceder a datos privados o suplantarte.
Secretos son las llaves del reino: claves API, contraseñas de base de datos, tokens privados, claves de firma. Si un extraño las obtiene, puede actuar como tu app.
Una variable de entorno es simplemente una ranura etiquetada que tu app lee cuando corre. Tu código busca una etiqueta (como STRIPE_SECRET_KEY) y usa el valor que esté guardado allí. Esta separación es la razón por la que las variables de entorno funcionan tan bien para claves API: el código puede quedarse igual, mientras el valor secreto queda fuera de tus prompts, archivos y repos.
Mantener código y secretos en lugares diferentes también facilita las correcciones. Si expones un secreto por error, puedes reemplazar el valor sin cambiar el código.
Una forma práctica de pensar en entornos es: mismas etiquetas, valores distintos.
Ejemplo: puedes usar la etiqueta PAYMENTS_KEY en todas partes, pero dev usa una clave de prueba, staging una clave restringida y prod la clave completa. Si despliegas con una plataforma como Koder.ai, esto encaja bien porque puedes desplegar la misma app a distintos entornos con configuraciones de entorno diferentes.
Un secreto es cualquier valor que da a alguien un poder que no debería tener. Si un extraño lo obtiene, puede iniciar sesión, gastar tu dinero, leer tus datos o hacerse pasar por tu app.
Los secretos comunes incluyen claves API, contraseñas de base de datos, tokens de acceso privados, claves de firma y secretos de webhooks. Si puede crear, borrar, cobrar, leer datos privados o firmar peticiones, trátalo como secreto.
Algunos valores parecen inofensivos pero siguen siendo sensibles. Los tokens de escritura son la trampa clásica: no parecen "contraseñas", pero permiten a un atacante subir archivos, enviar correos o escribir en tu base de datos. Lo mismo aplica a claves de administrador, archivos JSON de cuentas de servicio y cualquier token que parezca una larga cadena aleatoria.
No todo necesita manejo secreto. Usualmente no son secretos: feature flags (que solo cambian UI o comportamiento, no acceso), URLs públicas, texto de interfaz, IDs de analítica y IDs internos que por sí solos no permiten acceder a datos. Si está pensado para verse en el front end o en la documentación, probablemente no sea secreto.
Una prueba rápida: si te molestaría verlo pegado en un chat público o commiteado en un repo público, es un secreto.
Mantén una lista corta y escrita de los secretos que usa tu app. Para cada uno, anota para qué sirve (pagos, correo, base de datos, almacenamiento), dónde debería estar (dev, staging, prod), quién lo administra (tú, un compañero, una cuenta de vendor) y si debe ser solo lectura o con permisos de escritura. Esta lista será tu mapa cuando luego rotees claves sin adivinar.
La mayoría de las filtraciones no son por "hackers". Son momentos normales donde alguien copia un valor para salir del paso y luego olvida que sigue visible. Una buena regla: si puede buscarse, sincronizarse, reenviarse o compartirse por pantalla, trátalo como público.
El chat es un gran problema. La gente pega claves API completas en prompts, chats de equipo o mensajes de soporte porque es rápido. Pero los chats se guardan y se comparten. Si necesitas ayuda, pega solo los últimos 4–6 caracteres y el nombre de la clave, por ejemplo STRIPE_SECRET_KEY ...9f2a.
Git es la trampa clásica. Añades una clave a un archivo "solo por ahora", la comiteas y luego la borras. El secreto sigue en el historial de commits. También puede propagarse por forks, fragmentos copiados o diffs de pull request.
Capturas de pantalla y grabaciones filtran más de lo que la gente piensa. Un vídeo demo puede capturar una pantalla de ajustes, un comando en terminal o un mensaje de error mostrando un token. Incluso texto desenfocado puede ser arriesgado si otras partes son legibles.
Rastreadores de issues y apps de notas son otra fuente silenciosa. Tickets, checklists y docs compartidos se copian entre equipos y proveedores. Trátalos como registros públicos.
Unos hábitos previenen la mayoría de fugas:
Si estás construyendo en Koder.ai, aplica la misma mentalidad: guarda los valores sensibles en la configuración de entorno, no dentro del chat que define tu app.
El objetivo es simple: tu app debe leer los secretos del entorno, no del prompt, no del código y no de archivos que terminen en Git.
Un archivo .env es un archivo de texto plano en tu máquina que almacena pares clave-valor. Facilita la configuración local, pero también se filtra con facilidad, así que trátalo como una billetera.
Crea un archivo .env local y asegúrate de que Git lo ignore (normalmente via .gitignore). Si necesitas compartir los nombres de las variables con compañeros, comparte un archivo de ejemplo como .env.example que contenga solo marcadores de posición, jamás valores reales.
Elige nombres claros para que sea obvio qué son y dónde pertenecen:
OPENAI_API_KEYSTRIPE_SECRET_KEYDATABASE_URLSENDGRID_API_KEYS3_ACCESS_KEY_IDNombres buenos reducen errores cuando luego configuras dev, staging y producción.
Cuando la app arranca, pregunta al sistema operativo: "¿tienes un valor para OPENAI_API_KEY?" Si existe el valor, la app lo usa. Si falta, la app debería fallar pronto con un error claro, en lugar de ejecutarse con comportamiento roto.
Un hábito práctico: registra si una variable está presente (sí/no), pero nunca imprimas el secreto en sí.
No pegues claves en hilos de chat o tickets. Usa un gestor de contraseñas (bóveda compartida) u otro canal seguro y comparte solo lo que la persona necesita. Si alguien deja el equipo, rota la clave.
Ejemplo: una fundadora exporta un proyecto de Koder.ai y lo ejecuta localmente. Mantiene .env en su laptop, commitea solo .env.example y da acceso a las claves reales a compañeros a través de un gestor de contraseñas compartido.
Piensa en los entornos como tres habitaciones separadas.
Dev es tu laptop o un sandbox personal donde cambias rápido. Staging es una copia segura de producción donde pruebas la app completa con ajustes reales, pero sin impacto real en clientes. Prod es lo que usan los clientes.
La regla simple: mantiene los nombres de variable idénticos en todas partes y solo cambia los valores. Tu código lee STRIPE_SECRET_KEY en cada entorno, pero cada entorno proporciona una clave distinta.
Una pequeña tabla de mapeo (incluso una nota simple) ayuda:
| Nombre de variable (igual en todos lados) | Valor en Dev | Valor en Staging | Valor en Prod |
|---|---|---|---|
PAYMENTS_API_KEY | clave de prueba | clave de staging | clave en vivo |
APP_BASE_URL | URL localhost | dominio de staging | dominio personalizado |
DATABASE_URL | BD local | BD de staging | BD de prod |
Prod no debe reutilizar claves de dev. Las claves de dev se comparten entre compañeros y a veces tienen permisos amplios.
Para mantener los valores organizados con un equipo pequeño, acuerda algunas reglas:
STRIPE_KEY vs STRIPE_API_KEY).Si usas un builder hospedado como Koder.ai, trata cada objetivo de despliegue (dev, staging, prod) como un entorno separado con sus propios valores secretos, aunque el código sea el mismo.
Rotar un secreto significa reemplazar una clave API a propósito, en tu calendario. Bien hecho, la rotación es aburrida: creas la nueva clave, confirmas que todo sigue funcionando y luego deshabilitas la antigua.
El modelo mental más seguro es "dos claves por un tiempo corto." Muchos proveedores permiten más de una clave activa. Ese solapamiento mantiene la app en marcha mientras cambias la configuración.
Una ventana de rotación simple:
Si el proveedor no soporta claves múltiples activas, elige un horario de baja carga y espera un reinicio corto. El objetivo sigue siendo el mismo: cambiar el secreto en un solo lugar sin tocar el código.
Si crees que una clave se filtró, actúa primero e investiga después. Revoca o desactiva la clave inmediatamente y emite una nueva, luego actualiza tu variable de entorno. Cuando la app esté estable, busca dónde se escapó: prompts de chat, logs de build, capturas, commits antiguos o documentos compartidos.
Ejemplo: construiste un pequeño CRM en Koder.ai y usa una API de correo. Generas una clave nueva de correo, la colocas en los ajustes de entorno de la app, envías un correo de prueba y luego revocas la anterior.
CI/CD es una tubería automatizada que construye y despliega tu app cuando haces push, y a menudo necesita los mismos secretos que tu app. La regla principal: no introduzcas claves API en logs de build, código fuente o prompts de chat. Trata el pipeline como otra máquina que debe recibir secretos de forma controlada.
Intenta separar secretos necesarios para construir de los necesarios para ejecutar.
Los secretos de build solo se usan durante la etapa de compilación (por ejemplo, descargar un paquete privado). Los secretos de runtime se necesitan después del deploy (por ejemplo, llamar a Stripe o enviar correo). Si puedes mantener claves solo en runtime, reduces la posibilidad de que se incrusten en un bundle, queden en artefactos cacheados o se impriman en la salida del build.
Una comprobación rápida: si el secreto se necesita en el navegador del usuario, no es un secreto. Las "claves públicas" visibles en el navegador pueden estar bien, pero las claves de servidor deben quedarse en el servidor.
Usa el almacenamiento de secretos específico del entorno de tu plataforma de hosting para que dev, staging y prod tengan valores distintos.
Si despliegas con hosting de Koder.ai, establece los secretos como variables de entorno por entorno en lugar de pegar claves en el código o en archivos de configuración. Luego tu app las lee en tiempo de ejecución (por ejemplo, PAYMENTS_API_KEY en producción vs clave de prueba en staging).
Para mantener la producción segura, limita quién puede ver o cambiar secretos de prod. Mantén pequeño el grupo que puede "ver secretos" y separa permisos de despliegue de permisos para editar secretos cuando tu tooling lo permita. También usa claves separadas por entorno para que staging no pueda acceder a datos de prod.
La mayoría de las filtraciones son atajos cotidianos que perduran y se copian al siguiente proyecto.
Si una clave está dentro de tus archivos fuente, puede acabar en backups, capturas, zips compartidos y en el historial de git.
Solución:
.env a tu archivo de ignore antes del primer commit.Al pegar una clave real en un chat pierdes control de dónde se guarda o comparte ese texto. Si usas una herramienta de vibe-coding como Koder.ai, es tentador soltar todo en el chat. En su lugar, reemplaza secretos por placeholders como PAYMENTS_API_KEY=REDACTED y describe el síntoma.
Un buen hábito: copia mensajes de error, nunca credenciales.
Una clave usada en dev, staging y prod significa que una filtración es un incidente mayor. Si varios compañeros comparten la misma clave, tampoco puedes saber quién la usó.
Solución: crea claves separadas por entorno y, si el proveedor lo permite, por persona o por app.
Una trampa común es imprimir "toda la configuración" al arrancar. Eso suele incluir tokens.
Solución: registra solo lo necesario (por ejemplo, "Clave de Stripe cargada: sí") y enmascara valores (muestra los últimos 4 caracteres) cuando necesites identificar qué clave está activa.
Ejemplo: si staging falla, no imprimas la clave completa. Imprime STRIPE_KEY terminada en 9K2P para confirmar que desplegaste la correcta sin exponerla.
Antes de hacer shipping, haz una pasada tranquila enfocada solo en secretos.
api_key, secret, token y nombres de proveedores. También revisa docs compartidos, capturas y logs de chat. Si una clave apareció en git o en un doc, asúmela comprometida y reemplázala.Un ejemplo rápido: si tu app usa una API de pagos y una de correo, deberías tener dos conjuntos de claves para dev, staging y prod, y un responsable claro para cada una. Cuando despliegues (ya sea a través de tu setup de hosting o una plataforma como Koder.ai), mapea las vars de entorno correctas en cada entorno, no las copies en prompts, código o repos.
Maya es una fundadora no técnica que construye una web simple: los usuarios pagan una suscripción y la app envía recibos y restablecimientos de contraseña por correo. Ella mantiene sus prompts y repo limpios tratando los secretos como ajustes que viven fuera del código, inyectados en tiempo de ejecución usando variables de entorno.
Aquí hay un conjunto práctico de vars de entorno que define (los nombres permanecen iguales en todas partes; solo cambian los valores):
APP_ENV = development / staging / productionAPP_BASE_URL = http://localhost:3000 / https://staging.example.com / https://example.comPAYMENTS_PROVIDER_SECRET_KEY = clave de prueba (dev) / clave de prueba (staging) / clave en vivo (prod)EMAIL_PROVIDER_API_KEY = clave sandbox (dev) / clave restringida (staging) / clave completa (prod)DATABASE_URL = BD local (dev) / BD de staging (staging) / BD de producción (prod)Una regla simple ayuda: dev y staging deben usar modos de prueba y datos separados. Producción usa claves en vivo y datos reales. Así, un error en staging no cobrará tarjetas reales ni enviará correos a clientes reales.
Ahora un evento de rotación realista: un contratado con acceso se va del equipo. Maya asume que las claves antiguas pueden estar comprometidas. Genera claves nuevas en los paneles de pagos y correo, actualiza los valores de entorno en cada entorno y rota producción primero en una ventana tranquila, verifica inscripciones, pagos y correos, y solo entonces rota staging y dev. Si algo se rompe, restaura rápidamente la configuración conocida anterior.
Siguientes pasos para que esto no se vuelva un lío más adelante:
Escribe una página "Lista de Env Vars" para tu app (nombre, para qué sirve, dónde se configura y quién puede acceder). Pon una revisión mensual de 10 minutos en el calendario para eliminar claves no usadas y rotar cualquier cosa de alto riesgo.
Si ya estás construyendo con Koder.ai (koder.ai), ayuda a mantener esto organizado porque puedes gestionar despliegues y configuraciones de entorno en un solo lugar. Las snapshots y el rollback también son útiles cuando un cambio de config causa una caída y necesitas recuperar rápido.
Una clave API puede generar cargos inesperados muy rápido y, en algunos casos, dar acceso a datos privados o permitir acciones como enviar correos. Trátala como una contraseña: si otro la obtiene, a menudo puede actuar en nombre de tu app.
Pon los secretos en variables de entorno para que el valor viva fuera de tu código y fuera de cualquier cosa que puedas pegar, commitear o capturar en pantalla. Tu app lee el secreto en tiempo de ejecución por su nombre (por ejemplo STRIPE_SECRET_KEY), mientras el código permanece seguro para compartir.
Un secreto es todo aquello que permitiría a un extraño gastar dinero, acceder a datos privados o suplantar tu app. Claves API, contraseñas de base de datos, tokens privados, claves de firma y secretos de webhooks son secretos; identificadores públicos y configuraciones puramente de UI normalmente no lo son.
Las filtraciones más comunes ocurren en prompts de chat, chats de equipo, tickets, capturas de pantalla y commits en git (incluyendo el historial). Una buena práctica es asumir que cualquier cosa que sea buscable, sincronizada, reenviada o compartida por pantalla podría hacerse pública.
Puedes usar un archivo local .env en tu máquina para comodidad, pero nunca lo comitees. Mantén un .env local y commitea solo un .env.example con marcadores de posición para que los compañeros conozcan los nombres de las variables sin ver valores reales.
Usa los mismos nombres de variables en todos los entornos y cambia solo los valores. Por ejemplo, PAYMENTS_API_KEY existe en dev, staging y prod, pero dev usa una clave de prueba y prod la clave real.
No. Las claves de servidor nunca deben estar en código front-end porque cualquiera puede leerlas en el navegador. Si necesitas llamar a un servicio de forma segura, enruta la petición a través de tu backend y guarda el secreto en el servidor.
Crea primero una clave nueva, actualiza la variable de entorno, reinicia o despliega para que la app cargue el nuevo valor y verifica que el flujo real funciona. Cuando confirmes que la nueva clave está operativa, revoca la antigua para que no pueda usarse más.
Revoca o desactiva la clave expuesta de inmediato y genera una nueva; luego actualiza la configuración de entorno y redepliega. Cuando todo esté estable, busca dónde se filtró (logs de chat, commits, capturas, documentos compartidos) para limpiar la fuente de la fuga.
Almacena secretos en la configuración de entorno por entorno y mantenlos fuera del chat del proyecto y del código fuente. Si un cambio de configuración rompe algo, usa snapshots y rollback para volver a un estado conocido sin reintroducir claves filtradas.