Cómo prevenir, rotar y cuidar las API keys de proveedores de IA
Una API key de OpenAI, Anthropic, Google u otro proveedor de modelos no es un “detalle de setup”. Es una credencial que gasta cuota, puede leer o escribir datos según el permiso del producto, y —si se filtra— se convierte en costo inesperado o en abuso sobre tu cuenta.
Este artículo resume lo que OpenAI documenta en sus Production best practices y en Best practices for API key safety, más principios de equipo que sirven para cualquier vendor de IA. Sin inventar cifras: solo prácticas verificables.
Prevención: lo que no debería pasar nunca
OpenAI es explícito en dos puntos que los equipos todavía rompen con frecuencia:
- No hardcodear la key en el código ni exponerla en repositorios públicos. Guardala en un lugar seguro y exposela al runtime con variables de entorno o un servicio de gestión de secretos.
- Nunca desplegar la key en el cliente (browser, app móvil). Quien ve el front puede reusar esa key. Las llamadas van por tu backend.
De la guía de API key safety también salen reglas de higiene que valen el tiempo de escribirlas en el README del equipo:
- Una key por persona cuando el acceso es humano; no compartir la misma key entre compañeros (va contra los términos de uso de OpenAI).
- No commitear la key a git. Un repo privado no es un vault: un commit filtrado, un fork o un backup mal puesto alcanzan.
- Evitar pegar keys en tickets, screenshots de Slack o demos grabadas.
Para Anthropic, Google y el resto: marcar esto como buena práctica de equipo, no como cita inventada de cada vendor. La idea es la misma: secreto fuera del cliente, fuera del repo, con least privilege.
Almacenamiento: env vars y secret managers
En desarrollo local, una variable OPENAI_API_KEY (u otra convención del vendor) suele ser suficiente. En staging y producción, preferí un secret manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, etc.): cifrado en reposo, auditoría de acceso y rotación sin tocar la imagen del contenedor.
Checklist mínimo:
- La key no aparece en Dockerfiles, Compose sin secrets, Helm values commiteados ni scripts de CI en texto plano.
- CI/CD inyecta el secreto en runtime (OIDC + secret store, o el mecanismo de tu plataforma).
- Los logs y el APM no imprimen headers
Authorization. - El frontend nunca recibe la key del modelo; solo tokens de sesión de tu app.
Aislar: entornos y workloads
OpenAI recomienda crear proyectos separados para staging y producción en el dashboard: aislás pruebas, limitás quién toca prod y podés setear rate y spend limits por proyecto.
Buenas prácticas de equipo (aplican a cualquier proveedor):
- Keys distintas para dev / staging / prod.
- Keys distintas por workload (API de chat vs. batch vs. agentes) cuando el blast radius lo justifica.
- Acceso humano a prod acotado; en prod, preferí identidades de servicio, no keys personales.
Expiración y max lifetime (OpenAI)
OpenAI recomienda fuerte setear una fecha de expiración al crear una project API key y mantener un proceso de rotación regular.
Además, los administradores pueden imponer un máximo de vida de API keys a nivel organización o proyecto en Platform settings. Las keys nuevas tienen que respetar ese techo; el límite del proyecto no puede superar el de la organización. Así evitás keys “para siempre” que nadie recuerda.
Rotación segura (secuencia oficial)
Antes de que una key expire —o en el ciclo de rotación que definan— OpenAI describe este orden:
- Crear la key de reemplazo.
- Actualizar las aplicaciones / secret stores para usarla.
- Verificar que el tráfico nuevo funciona.
- Revocar la key vieja.
Al revés en producción es downtime garantizado. Documentá el runbook en una página corta del wiki del equipo y ensayalo una vez en staging.
Si el vendor lo permite (OpenAI lo menciona para workloads soportados), evaluá workload identity federation: intercambiar una identidad confiable por un access token de vida corta en lugar de guardar una API key larga.
Governance: quién puede crear qué
En Platform settings, API Key Governance deja que admins de org o proyecto restrinjan la creación:
- solo keys de service account,
- solo keys de proyecto owned por usuario, o
- deshabilitar la creación de keys nuevas.
Las restricciones de organización tienen prioridad: el proyecto puede sumar restricciones, no aflojar las de arriba. Importante: esto aplica a creación nueva; las keys existentes no se reescriben solas.
Para prod, la dirección sensata es: service accounts con el mínimo permiso, dueño claro y rotación calendarizada.
Monitoreo, spend y qué hacer si hay leak
OpenAI apunta al Usage page para monitorear uso por key (con tracking habilitado). Las keys generadas antes del 20 de diciembre de 2023 pueden no tener tracking por defecto: hay que habilitarlo en el dashboard de keys. Las posteriores ya lo traen; el uso viejo sin tracking aparece como Untracked.
Para costos:
- alertas de spend en la página de limits,
- y, si aplica, un hard spend limit (corta tráfico cuando el gasto trackeado llega al tope; conviene leer la guía de spend limits antes de activarlo en prod).
Si sospechás un leak (Usage anómalo, key en un repo público, alerta de secret scanning):
- Rotá de inmediato desde la página de API Keys (crear reemplazo → actualizar prod → revocar la comprometida).
- Revisá Usage y alinealo con el trabajo real del equipo.
- Contactá a OpenAI vía help.openai.com si necesitás investigación adicional.
La guía de safety también menciona IP allowlisting (solo IPs/rangos de confianza) y, para algunos escenarios Azure, Private Link — capas de red encima de la autenticación por key.
Checklist de equipo (copiá y adaptá)
- Ninguna key de IA en git, imágenes Docker ni clientes.
- Secret manager (o al menos env vars inyectadas) en staging y prod.
- Proyectos / keys separados por entorno; prod con acceso restringido.
- Expiration al crear keys; max lifetime forzado en Platform settings (OpenAI).
- Runbook de rotación: crear → deploy → verificar → revocar.
- Governance: quién puede crear keys; service accounts en prod.
- Tracking en Usage; alertas de spend; dueño on-call del incidente.
- Playbook de leak de una página, ensayado en staging.
- Misma higiene para Anthropic, Google y otros vendors del stack.
Fuentes
Lecturas relacionadas
Si estás armando agentes que actúan en sistemas (no solo chat), sumá controles de runtime y de identidad de máquina; la key del modelo es solo una pieza del perímetro.