Una clave por entorno, nunca en el cliente

Una startup usa la misma clave en las notebooks de los desarrolladores, en CI y en producción; está en un .env que se commiteó hace un año. Se pierde una notebook y nadie sabe qué se rompe si la revocan. Otra empresa metió la clave dentro de la app móvil para salir rápido: a las dos semanas el uso se triplicó con los mismos usuarios y llegan pedidos desde IP desconocidas. Las dos situaciones se evitan con tres reglas.

Regla 1: la clave vive en el servidor

Una clave de API (API key) dentro de un frontend, una app móvil o un binario de escritorio es pública: cualquiera la extrae. Ofuscarla solo demora a quien la busca.

El diseño correcto:

• el cliente habla con tu backend, que hace la autenticación (authentication) de cada usuario con tu sistema de sesiones;
• el backend llama a la API con la clave, que nunca sale del servidor;
• cada pedido queda registrado con el usuario que lo hizo, así sabés quién consume y podés poner límites por usuario.

Si la clave ya se filtró, primero se revoca y después se arregla la arquitectura. Bajar el límite de gasto o filtrar por user agent no cierra el agujero.

Regla 2: una clave por entorno

• Separá desarrollo, CI y producción. Con espacios de trabajo (workspaces) de la Consola, cada entorno tiene sus propias claves y su propio límite de gasto. Revocar la de desarrollo no tira abajo producción.
• Guardalas en un gestor de secretos (secrets manager): el del proveedor de nube o el de tu plataforma de CI. Nunca en el repositorio, ni siquiera en uno privado, ni en un .env cifrado con la contraseña compartida.
• Dale a cada clave el alcance mínimo: una por servicio o equipo, no una para todo.
• Fuera del contexto del modelo: una clave no va en un prompt, en CLAUDE.md ni en la configuración de un servidor MCP que comparten otros. Las credenciales de sistemas externos quedan del lado del servidor que ejecuta la herramienta.

Regla 3: rotar y monitorear

• Ante una filtración, la respuesta es inmediata: revocar, emitir una clave nueva y reemplazarla en el gestor de secretos. Rotar “cada trimestre” no sirve si la clave expuesta sigue activa hasta entonces.
• La rotación de claves (key rotation) periódica es más fácil cuando cada entorno tiene la suya y el código la lee del gestor: se cambia en un lugar y no hace falta tocar código.
• El monitoreo de accesos (access monitoring) detecta lo raro: uso por clave y por entorno (la Consola permite exportar el uso por clave y modelo), alertas ante picos o IP desconocidas, y registros de qué usuario hizo cada pedido.

Identidad y nivel de acceso

Autenticar dice quién es; además hay que verificar qué puede hacer. Si una función del agente es solo para supervisores, el backend controla el rol de la sesión antes de ejecutarla, en lugar de confiar en lo que diga el usuario en el chat o en un parámetro que elige el modelo.

Las trampas típicas

• Clave en el bundle de la app o en una variable de entorno del build del frontend.
• Una sola clave compartida por todos los entornos.
• Mover el archivo a otro nombre y agregarlo a .gitignore sin rotar la clave expuesta.
• Ofuscar la clave o restringir por user agent.
• Cifrar el .env dentro del repositorio y compartir la contraseña.
• Bajar el límite de gasto como única respuesta a un abuso.

En el examen

Si el escenario tiene una clave en el cliente y uso que no cierra con los usuarios reales, buscá revocarla y pasar las llamadas por un backend que autentique y registre por usuario. Si tiene una clave compartida o commiteada, buscá rotarla ya y separar claves por entorno en un gestor de secretos.