Gestión segura de claves API para productos de IA

La gestión segura de claves API para productos de IA no es solo una cuestión de colocar una credencial de proveedor en una bóveda. Las aplicaciones de IA envían prompts, archivos, contexto recuperado, argumentos de herramientas y resultados del modelo a través de sistemas que a menudo abarcan varios proveedores y entornos. Una clave puede estar perfectamente cifrada en reposo mientras la ruta de la solicitud circundante sigue exponiendo datos sensibles a través de bundles del navegador, registros de depuración, salida de CI, exportaciones de soporte o un servicio de enrutamiento con permisos excesivos.

Por tanto, el objetivo práctico es más amplio: mantener las claves de proveedor de larga duración fuera de los clientes no confiables, dar a cada carga de trabajo la identidad útil más pequeña posible, controlar qué datos pueden cruzar cada límite del modelo y hacer que la rotación y la revocación sean rutinarias en lugar de disruptivas.

Esta guía ofrece a los equipos de plataforma, seguridad y productos de IA un modelo operativo que pueden implementar. Incluye un modelo de amenazas, una plantilla de inventario de claves, una arquitectura de plano de control, un procedimiento de rotación sin tiempo de inactividad, reglas de registro, salvaguardas de CI/CD, un flujo de trabajo de respuesta a incidentes y una lista de verificación de producción.

Las cinco fronteras que una clave de IA puede cruzar

Empiece por mapear los lugares donde puede moverse un secreto o los datos que autoriza. La mayoría de los fallos se producen porque los equipos protegen la clave del proveedor, pero pasan por alto una de estas fronteras adyacentes.

Este mapa de fronteras cambia la pregunta de diseño de “¿Dónde almacenamos la clave?” a “¿Qué identidad puede hacer qué solicitud, con qué datos, a través de qué ruta, y qué evidencia queda después?”

Use un modelo de custodia de claves del lado del servidor

Las credenciales de proveedor de larga duración no deben entregarse a clientes de navegador, móviles, escritorio o extensiones. Cualquier cosa enviada a un dispositivo de usuario final debe considerarse recuperable por ese usuario o por malware que se ejecute con los mismos privilegios.

Un patrón más seguro es:

1. El cliente se autentica en su backend mediante una sesión de usuario, una credencial de dispositivo o un token de aplicación de corta duración.
2. Su backend autoriza la funcionalidad solicitada y aplica límites por usuario o por inquilino.
3. Una pasarela o integración del lado del servidor elige el proveedor y el modelo aprobados.
4. La clave del proveedor se recupera en tiempo de ejecución o se pone a disposición de la carga de trabajo de confianza a través de la plataforma de implementación.
5. La respuesta del proveedor vuelve a través del mismo límite de política.

El cliente nunca necesita el secreto del proveedor. Solo recibe autorización para llamar a su producto dentro de los límites que usted defina.

Para agentes de programación y herramientas de desarrollo locales, use el mismo principio con un modelo de excepción deliberado. Un desarrollador puede necesitar una credencial local, pero debe ser una credencial de producto o de pasarela con revocación, atribución de uso y alcance limitado, no una clave de proveedor compartida de toda la organización copiada en dotfiles por toda la empresa.

Compile un inventario de claves antes de rotar nada

Los proyectos de rotación fracasan cuando los equipos no saben qué carga de trabajo usa una clave. Cree un inventario legible por máquina y asigne un responsable antes de cambiar credenciales.

Como mínimo, registre:

No coloque el valor de la clave en el inventario. Almacene solo metadatos y una referencia al secreto administrado.

Separe las identidades por entorno, carga de trabajo y riesgo

El anti-patrón más común es una sola clave de producción compartida por cada servicio. Es conveniente hasta que un repositorio, un ejecutor de pruebas, el portátil de un contratista o una transcripción de soporte la filtra. Entonces el equipo no puede revocar la clave sin interrumpir productos no relacionados.

Prefiera identidades separadas para:

• Producción, staging, desarrollo y pruebas locales.
• Tráfico de cara al cliente, herramientas internas, trabajos por lotes y canalizaciones de evaluación.
• Flujos de trabajo de alto riesgo que pueden invocar herramientas o procesar datos confidenciales.
• Diferentes unidades de negocio o inquilinos cuando los límites contractuales requieran separación.
• Acceso de emergencia o de tipo break-glass, que debe permanecer deshabilitado o estrictamente controlado durante la operación normal.

Cuando un proveedor ofrezca restricciones, aplíquelas. Las restricciones pueden incluir APIs permitidas, modelos, redes de origen, proyectos, referrers, aplicaciones o cuotas. La guía de claves API de Google Cloud, por ejemplo, recomienda restringir las claves, aislarlas, eliminar las claves no necesarias, evitar confirmarlas en el repositorio y supervisar su uso.

Si el proveedor no ofrece controles suficientemente granulares, aplíquelos en su propia pasarela. Una pasarela central puede validar la carga de trabajo que llama, asignarla a una ruta aprobada, aplicar presupuestos y límites de frecuencia, y mantener las credenciales del proveedor detrás de un único perímetro revisado del lado del servidor. Revise la guía de arquitectura de pasarela de API de IA más amplia para el diseño de enrutamiento y failover.

Trate la gobernanza de prompts y registros como parte de la gestión de claves

Una clave API autoriza una ruta de datos. Proteger la clave sin controlar esa ruta deja sin resolver el principal riesgo específico de IA.

Antes de enrutar una solicitud, clasifique la carga útil y aplique una regla de mínimo necesario:

• Elimine credenciales, tokens, cookies, claves privadas y cadenas de conexión.
• Excluya los campos que el modelo no necesita.
• Tokenice o pseudonimice los identificadores directos cuando la tarea pueda funcionar sin ellos.
• Rechace datos regulados no admitidos o restringidos contractualmente.
• Separe las instrucciones del sistema del contenido no confiable del usuario o recuperado.
• Valide los argumentos de las herramientas antes de que un agente pueda llamar a sistemas externos.

Los registros necesitan un esquema explícito. No confíe en que los desarrolladores recuerden no registrar un objeto de solicitud. Defina qué campos están permitidos y luego descarte o transforme todo lo demás.

Un evento de producción útil puede contener:

{
  "request_id": "req_01J...",
  "tenant_id_hash": "tnt_7f2...",
  "workload": "support-chat-api",
  "route_policy": "support-low-risk-v3",
  "provider": "selected-provider",
  "model": "selected-model",
  "input_tokens": 842,
  "output_tokens": 211,
  "latency_ms": 1370,
  "status": 200,
  "key_version": "v12",
  "redaction_policy": "customer-support-v4"
}

No debe contener la cabecera de autorización, la clave bruta del proveedor, el prompt completo, el documento cargado, el argumento de la herramienta sin redacción ni la salida completa del modelo por defecto. Si la captura de la carga útil es necesaria para una evaluación o incidente estrictamente controlados, hágala con un límite temporal, control de acceso y claramente separada de la telemetría rutinaria.

La OWASP Logging Cheat Sheet proporciona una base útil para excluir tokens de acceso, contraseñas, claves de cifrado y otros datos sensibles de los registros de la aplicación.

Diseñe la rotación de claves API sin tiempo de inactividad

La rotación solo es un control si puede realizarse de forma segura. Un runbook que provoque una interrupción se pospondrá hasta una emergencia.

Use una secuencia de clave dual o de secreto versionado cuando el proveedor admita credenciales superpuestas:

1. Cree una nueva clave del proveedor. Aplique las mismas restricciones o unas más estrictas que las de la clave antigua.
2. Guárdela como una nueva versión del secreto. No sobrescriba el valor antiguo en el lugar si su plataforma admite versiones o alias.
3. Implemente lectores que acepten la nueva versión. Actualice el gateway o las cargas de trabajo para resolver el alias o la versión actual.
4. Desplace el tráfico y observe. Confirme las solicitudes correctas, los modelos esperados, el gasto, los límites de tasa y las tasas de error usando la nueva versión de la clave.
5. Elimine los consumidores antiguos. Revise los inventarios de despliegue, trabajos, workers y entornos de recuperación ante desastres.
6. Revocar la clave antigua. No se limite a dejar de usarla; invalídela en el proveedor.
7. Verifique el rechazo. Una prueba controlada debe confirmar que la credencial antigua ya no funciona.
8. Registre la evidencia. Guarde marcas de tiempo, responsables, cargas de trabajo afectadas, resultados de validación y la próxima fecha de revisión.

Para un sistema que admite la selección de versiones de clave, la aplicación debe referirse a un alias estable en lugar de codificar de forma fija una versión del secreto:

type ProviderCredential = {
  value: string;
  version: string;
};

async function loadProviderCredential(): Promise<ProviderCredential> {
  const activeVersion = await secretStore.resolveAlias("ai/provider/active");
  const value = await secretStore.readVersion("ai/provider", activeVersion);

  return { value, version: activeVersion };
}

No imprima value, serialice el objeto devuelto ni lo adjunte a un error. Registre solo el identificador de versión que no es secreto.

La OWASP Secrets Management Cheat Sheet recomienda planificar el ciclo de vida completo del secreto, incluida la creación, la rotación, la revocación, la caducidad, la auditoría, la copia de seguridad y el acceso de emergencia. También enfatiza automatizar la rotación cuando sea práctico.

Evite que los secretos entren en repositorios y registros de CI

Los gestores de secretos no ayudan después de que una credencial se copia en el código fuente, un fixture, un artefacto de compilación o una transcripción de CI.

Use controles en tres etapas:

Antes del commit

• Proporcione archivos .env.example con marcadores de posición, nunca credenciales funcionales.
• Mantenga los archivos locales de secretos fuera del control de versiones.
• Ejecute un escáner rápido de secretos en los hooks de pre-commit para patrones comunes de proveedores y valores de alta entropía.
• Enseñe a los desarrolladores que eliminar un secreto en un commit posterior no lo elimina del historial.

En el push y la solicitud de extracción

• Habilite el escaneo de secretos en el repositorio y la protección contra push donde esté disponible.
• Añada patrones personalizados para tokens internos de gateway que los escáneres públicos no reconocerán.
• Exija una razón de bypass documentada y derive los bypass a revisión de seguridad.
• Escanee archivos generados, notebooks, instantáneas de pruebas y planes de infraestructura, no solo el código fuente de la aplicación.

GitHub documenta la protección en el push como una forma de analizar durante el proceso de push y bloquear los secretos detectados antes de que entren en un repositorio. La detección no es una razón para conservar la clave: trate cualquier credencial confirmada y comprometida como expuesta y gírela.

Durante CI/CD

• Prefiera la identidad de carga de trabajo o la federación de corta duración frente a credenciales de nube almacenadas.
• Exponga un secreto solo al trabajo y al paso que lo necesiten.
• Enmascare los valores secretos conocidos, pero no dependa del enmascaramiento como control principal.
• Deshabilite el seguimiento de shell alrededor de la recuperación del secreto.
• Impida que código no confiable de forks acceda a los secretos de despliegue.
• Revise artefactos, cachés, volcados de memoria y informes de pruebas en busca de capturas accidentales.

Monitoree el uso sin registrar el secreto

Un buen monitoreo responde a “¿quién usó qué autorización?” sin registrar la autorización نفسها.

Haga seguimiento de:

• Carga de trabajo, entorno, inquilino o proyecto, y versión de la clave.
• Proveedor, modelo, política de ruta y ruta de respaldo.
• Conteos de solicitudes, volumen de tokens, gasto, latencia y clase de error.
• Red de origen o identidad de despliegue cuando sea útil.
• Acceso al gestor de secretos, incluidas las lecturas denegadas.
• Creación de claves, cambios de restricciones, rotación, revocación y eliminación.
• Uso repentino desde un entorno, geografía, modelo o ventana temporal inesperados.

Configure alertas en torno al comportamiento, no solo al gasto total. Una clave robada de bajo presupuesto aún puede exponer prompts o sondear flujos de trabajo internos. A la inversa, un trabajo por lotes legítimo puede crear un pico de gasto sin compromiso de credenciales. Correlacione el uso del proveedor con los IDs de solicitud de la aplicación, las decisiones de política del gateway, los eventos de despliegue y los registros de auditoría del gestor de secretos.

Para controles de tráfico que complementan los controles de credenciales, utilice la guía de límites de tasa de LLM y el playbook de enrutamiento de fallback de la API de LLM.

Use un reloj de incidente de exposición a revocación

Cuando una clave puede estar expuesta, el primer objetivo es la contención, no probar si un atacante la usó.

Ejecute esta secuencia:

1. Declara la credencial como sospechosa. Registra cuándo y dónde pudo haber sido expuesta.
2. Crea un reemplazo a través del proceso controlado normal. No pegues una nueva clave en el chat para acelerar el incidente.
3. Traslada las cargas de trabajo legítimas al reemplazo. Usa el procedimiento de rotación preparado.
4. Revoca la clave sospechosa. Si la revocación inmediata causara un daño inaceptable, aísla las rutas y reduce los límites mientras completas el cambio.
5. Busca en cada ubicación de copias. Revisa el historial del código fuente, los registros de CI, los artefactos, las capas de contenedores, los sistemas de soporte, los paneles, los cuadernos, la configuración local y las copias de seguridad.
6. Revisa las rutas de datos autorizadas. Determina a qué prompts, salidas, archivos, herramientas o modelos podía acceder la clave, no solo su alcance de facturación.
7. Correla la actividad. Compara el uso del proveedor, los registros del gateway, los despliegues, las lecturas de secretos y la actividad de los usuarios.
8. Notifica a los propietarios adecuados. Involucra a los equipos de seguridad, plataforma, legal, privacidad y clientes según los datos y los contratos implicados.
9. Elimina la causa raíz. Añade el escáner, la restricción, el límite de identidad o el filtro de registros que faltaba.
10. Mide el tiempo. Registra el tiempo hasta la detección, el reemplazo, el cambio de tráfico, la revocación y la verificación.

La métrica más accionable suele ser el tiempo de exposición a revocación: cuánto tiempo una credencial sospechosa sigue siendo utilizable después de que la organización dispone de evidencia creíble de su exposición. Reducir ese intervalo requiere propiedad preparada, inventario, automatización y rotación probada, no un documento de políticas más largo.

Reference architecture for multi-provider AI products

Una configuración segura multi-proveedor puede organizarse en cinco capas:

1. Capa de identidad del cliente: autentica al usuario, dispositivo, agente o aplicación sin exponer credenciales del proveedor.
2. Capa de autorización de la aplicación: verifica los derechos del producto, los límites del inquilino, el acceso a funciones y los presupuestos.
3. Capa de políticas de datos: clasifica y redacta prompts, archivos, contexto recuperado y argumentos de herramientas.
4. Capa de gateway y enrutamiento: selecciona modelos aprobados, aplica cuotas, registra atribución no confidencial y gestiona el failover.
5. Capa de credenciales del proveedor: almacena credenciales de proveedores aisladas, rota versiones y las expone solo a la carga de trabajo de enrutamiento confiable.

Este diseño limita el radio de impacto. Un token de cliente comprometido no revela automáticamente una clave de proveedor. Una identidad de carga de trabajo comprometida no debería conceder acceso a todos los proveedores. Una credencial de proveedor filtrada no debería autorizar todos los entornos. Un fallo de registro no debería exponer tanto el secreto como la carga útil completa.

El posicionamiento de producto de Flatkey es un único endpoint compatible con OpenAI y acceso unificado entre múltiples proveedores de modelos. Eso puede reducir el número de integraciones específicas de cada proveedor que mantiene una aplicación, pero una pasarela no elimina su responsabilidad de asegurar la autenticación del cliente, clasificar los datos de las solicitudes, configurar los registros, asignar responsables y probar la revocación. Evalúe los controles exactos disponibles para su cuenta y arquitectura antes del despliegue en producción. Puede empezar con la guía de integración de Flatkey y revisar el acceso actual a modelos y los precios.

Lista de verificación de producción

Use esta lista de verificación antes del lanzamiento y durante las revisiones trimestrales de controles.

Custodia e identidad

• Ninguna clave persistente del proveedor se incluye en el código del navegador, móvil, escritorio o extensiones.
• Cada carga de trabajo de producción tiene un propietario identificable y una ruta de credenciales.
• Producción, preproducción, desarrollo, evaluación y acceso local están separados.
• Cuando es posible, las claves humanas compartidas se han reemplazado por identidades de carga de trabajo o de pasarela.
• Las restricciones del proveedor y de la pasarela se establecen con el alcance más estrecho posible.

Almacenamiento y entrega

• La fuente de verdad es un almacén de secretos gestionado o un enlace de despliegue controlado.
• Las aplicaciones recuperan los secretos solo en tiempo de ejecución y no los imprimen ni serializan.
• Los trabajos de CI reciben solo los secretos necesarios para el paso requerido.
• El acceso a los secretos y los cambios administrativos se auditan.
• El acceso de emergencia está documentado, limitado en el tiempo y probado.

Datos y observabilidad

• Los encabezados de autorización y los valores de clave se excluyen de los registros, trazas, errores y exportaciones de soporte.
• El registro de prompts, salidas, archivos y argumentos de herramientas sigue un esquema de lista de अनुमति.
• La redacción se realiza antes del enrutamiento a múltiples proveedores.
• El uso puede atribuirse a carga de trabajo, entorno, ruta, proveedor, modelo y versión de clave.
• Las alertas cubren rutas e identidades inusuales, así como el gasto.

Rotación y respuesta

• Existe un runbook probado de rotación de doble clave o de secreto versionado.
• Las claves antiguas se revocan en el proveedor y se verifica que no sean utilizables.
• El análisis de secretos y la protección de envío cubren los repositorios y los artefactos generados.
• Una sospecha de filtración desencadena una contención inmediata sin esperar pruebas de abuso.
• El tiempo desde la exposición hasta la revocación se mide después de simulacros e incidentes.

Preguntas frecuentes

¿Qué es la gestión segura de claves API para productos de IA?

Es la práctica de controlar el ciclo de vida completo y la ruta de solicitud de las credenciales utilizadas para llamar a modelos de IA. Incluye la custodia en el lado del servidor, la identidad de la carga de trabajo, el mínimo privilegio, el almacenamiento de secretos, la política de enrutamiento, la gobernanza de prompts y registros, la rotación, la supervisión y la respuesta a incidentes.

¿Debe almacenarse una clave API de IA en una variable de entorno?

Una variable de entorno puede ser un mecanismo de entrega, pero no es un sistema de gestión completo. El secreto sigue necesitando una fuente de verdad controlada, acceso restringido al despliegue, rotación, auditoría y protección frente a volcados de procesos, registros, puntos de depuración y procesos hijos heredados. Prefiera la inyección de secretos nativa de la plataforma o la recuperación en tiempo de ejecución cuando mejore esos controles.

¿Con qué frecuencia deben rotarse las claves API de IA?

Utilice las capacidades del proveedor, su modelo de amenazas, los contratos y la política interna para definir el intervalo. Más importante que elegir un número de calendario arbitrario es demostrar que la rotación está automatizada o ensayada, que las claves antiguas se revocan, que las claves sospechosas pueden reemplazarse de inmediato y que las credenciales obsoletas no pueden permanecer sin ser detectadas.

¿Puede un navegador llamar directamente a un proveedor de IA con una clave restringida?

Algunos proveedores admiten restricciones orientadas al cliente para APIs específicas, pero un producto de IA en producción debe asumir que una credencial enviada puede recuperarse. Un backend o gateway suele ofrecer un control más sólido sobre la autorización de usuarios, las cuotas, la redacción de prompts, la selección de proveedor, la respuesta ante abusos y la revocación de claves.

¿Es más segura una sola clave de gateway que muchas claves de proveedor?

Puede reducir la dispersión de credenciales en el código de la aplicación, pero concentra la autoridad en el gateway. La credencial del gateway debe tener un alcance definido, ser atribuible, estar limitada por tasa, monitorizada, rotatable y protegida frente a los clientes. Las credenciales del proveedor detrás de ella siguen necesitando aislamiento y gestión de ciclo de vida.

¿Qué debemos hacer si una clave API aparece en el historial de Git?

Trátela como comprometida. Révoquela o rote la clave, sustituya a los consumidores legítimos, revise la actividad del proveedor y del gateway, elimine el valor de las ramas activas y de los artefactos relevantes, y añada análisis preventivo. Reescribir el historial no hace segura una credencial que sigue siendo válida.

Fuentes y lecturas adicionales

• OWASP Secrets Management Cheat Sheet
• OWASP Logging Cheat Sheet
• GitHub: About push protection
• Google Cloud: Best practices for managing API keys