Buenas prácticas de gestión de claves API para productos de IA (lista de verificación de 2026)

Buenas prácticas de gestión de claves API para productos de IA (lista de verificación de 2026)

Las buenas prácticas de gestión de claves API se resumen en cinco puntos: mantener las claves en el servidor y fuera del código, asignar a cada entorno y carga de trabajo una clave propia con permisos limitados, almacenarlas en un gestor de secretos, rotarlas y revocarlas según un calendario probado, y supervisar su uso sin registrar nunca la propia clave. En los productos de IA hay más en juego que en la mayoría de las API, porque una clave de acceso a modelos filtrada puede generar una factura elevada en cuestión de horas y también autorizar el acceso a prompts, archivos y llamadas a herramientas.

Esta guía convierte esos principios en una lista de verificación que pueden aplicar los equipos de plataforma, seguridad y producto de IA. Abarca el ciclo de vida de las claves, una plantilla de inventario, la rotación sin interrupciones, las medidas de protección en CI/CD, un procedimiento de respuesta a incidentes y código para generar, almacenar y verificar claves. Entre las fuentes se incluyen la guía de gestión de secretos de OWASP, las buenas prácticas de Google Cloud para claves API y la documentación de GitHub sobre detección de secretos, todas consultadas el 27 de octubre de 2026.

Buenas prácticas de gestión de claves API: lista rápida

#	Buena práctica	Qué evita
1	No incrustes nunca claves en el código fuente, los notebooks ni las aplicaciones cliente	Filtraciones a través del historial de Git, los paquetes del navegador y los binarios móviles
2	Mantén las claves del proveedor en el servidor; entrega a los clientes tokens de sesión de corta duración	Que usuarios o programas maliciosos extraigan tu clave de un dispositivo
3	Usa una clave por entorno, aplicación y miembro del equipo	Que una filtración deje todo fuera de servicio al revocar la clave
4	Aplica las restricciones más estrictas disponibles: API, modelos, IP y cuotas	Que las claves robadas puedan usarse para cualquier fin
5	Almacena las claves en un gestor de secretos, no en tickets, chats ni wikis	Copias que no puedes localizar ni rotar
6	Mantén un inventario de claves con responsable, carga de trabajo y fecha de rotación	Que la rotación interrumpa servicios consumidores desconocidos
7	Rota las claves según un calendario, con un periodo de coexistencia, y después revoca la clave anterior	Claves de larga duración que siguen activas tras la salida de empleados y proveedores
8	Elimina las claves que ya no uses	Claves olvidadas con permisos activos
9	Activa la detección de secretos y la protección de los envíos al repositorio	Que las claves lleguen a un repositorio público o compartido
10	No registres nunca claves ni cabeceras de autorización; registra un ID o una versión de la clave	Filtraciones de secretos a través de registros, trazas e informes de errores
11	Establece límites de gasto y alertas ante usos inusuales	Facturas inesperadas por una clave robada o un uso descontrolado
12	Prepara un procedimiento de respuesta a incidentes que priorice la revocación	Una exposición prolongada mientras los equipos debaten si se ha aprovechado la filtración

El resto de esta guía explica cómo aplicar cada práctica a las cargas de trabajo de IA, donde una clave hace más que autenticar: autoriza una vía de acceso a datos para prompts, documentos y respuestas de los modelos.

El ciclo de vida de las claves API

OWASP recomienda gestionar los secretos durante todo su ciclo de vida: creación, rotación, revocación y caducidad, con auditorías en cada paso (guía de gestión de secretos de OWASP). En el caso de una clave API de IA, ese ciclo es el siguiente:

Etapa	Acción del responsable	Evidencias que conservar
Solicitud	Justificar la carga de trabajo, el entorno y los modelos necesarios	Ticket o entrada en el inventario
Creación	Generarla en la consola o la API del proveedor con un nombre descriptivo	ID de la clave, fecha y hora de creación, creador
Restricción	Limitar modelos, API, redes y presupuesto	Configuración de las restricciones
Almacenamiento	Guardarla directamente en un gestor de secretos; no pegarla nunca en otro lugar	Ruta del secreto y política de acceso
Entrega	Inyectarla en tiempo de ejecución en la única carga de trabajo que la necesita	Vinculación del despliegue
Supervisión	Hacer seguimiento de solicitudes, tokens, gasto y último uso	Panel de uso y alertas
Rotación	Crear una sustituta, migrar a ella y verificar	Registro de rotación
Revocación	Invalidarla en el proveedor y confirmar un 401	Fecha y hora de revocación y resultado de la prueba

Los cinco límites que puede atravesar una clave de IA

Empieza por identificar los puntos por los que pueden circular un secreto o los datos a los que da acceso. La mayoría de los fallos se producen porque los equipos protegen la clave del proveedor, pero pasan por alto uno de estos límites adyacentes.

Límite	Fallo habitual	Control necesario
Del cliente a la aplicación	Se incluye una clave del proveedor en un paquete del navegador, un binario móvil, una aplicación de escritorio o una extensión	Mantener las claves del proveedor en el servidor; emitir credenciales de usuario o de sesión de corta duración para los clientes
De la aplicación a la pasarela	Todos los servicios comparten una clave sin restricciones	Usar identidades de carga de trabajo, tokens de pasarela con permisos limitados, cuotas y una política de rutas explícita
De la pasarela al proveedor	Una credencial permite acceder a todos los modelos, proyectos o entornos	Separar las claves por proveedor, entorno, carga de trabajo y nivel de riesgo cuando sea posible
De la solicitud a los registros	Las cabeceras de autorización, los prompts, los archivos o las respuestas aparecen en las trazas	Excluir los campos secretos, minimizar el registro del contenido, tokenizar los identificadores y probar la ocultación de datos sensibles
Operaciones humanas	Se pegan claves en tickets, chats, procedimientos operativos o herramientas de soporte	Usar flujos de acceso controlados, recuperación auditada, procedimientos de acceso de emergencia y caducidad automática

Este mapa de límites cambia la pregunta de diseño de «¿Dónde almacenamos la clave?» a «¿Qué identidad puede realizar qué solicitud, con qué datos, a través de qué ruta y qué evidencias quedan después?».

Usa un modelo de custodia de claves en el servidor

Las credenciales de larga duración de los proveedores no deben entregarse a clientes de navegador, móviles, de escritorio ni extensiones. Debe asumirse que cualquier elemento distribuido a un dispositivo de usuario final puede ser extraído por ese usuario o por software malicioso que se ejecute con los mismos privilegios.

Un patrón más seguro es el siguiente:

1. El cliente se autentica en tu backend mediante una sesión de usuario, una credencial de dispositivo o un token de aplicación de corta duración.
2. Tu backend autoriza la función solicitada y aplica límites por usuario o por tenant.
3. Una pasarela o integración en el servidor selecciona 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 despliegue.
5. La respuesta del proveedor regresa a través del mismo límite de aplicación de políticas.

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

Para los agentes de programación y las herramientas locales de desarrollo, aplica el mismo principio con un modelo de excepciones definido expresamente. Un desarrollador puede necesitar una credencial local, pero debe ser una credencial del producto o de la pasarela que permita revocación, atribución del uso y un alcance limitado, en lugar de una clave del proveedor compartida por toda la organización y copiada en archivos de configuración ocultos por toda la empresa.

Crea un inventario de claves antes de rotar nada

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

Como mínimo, registra lo siguiente:

Campo	Ejemplo	Por qué importa
ID del secreto	prod-support-chat-anthropic-01	Una referencia interna estable que no es el valor del secreto
Proveedor y proyecto	Cuenta del proveedor + identificador del proyecto	Define el alcance externo del impacto
Entorno	Desarrollo, preproducción, producción	Evita que los sistemas de prueba hereden los permisos de producción
Carga de trabajo	support-chat-api	Permite atribuir el uso y revocar de forma selectiva
Responsable	Equipo y rotación de guardias	Define las responsabilidades durante los incidentes
Ubicación de almacenamiento	Ruta en el gestor de secretos o vinculación del despliegue	Indica dónde reside la fuente de referencia
Modelos/rutas permitidos	Familia de modelos aprobada o política de la pasarela	Limita los usos inesperados
Límites de gasto y solicitudes	Presupuesto de la carga de trabajo, RPM, TPM o controles de concurrencia	Limita el abuso y la automatización descontrolada
Creación y última rotación	Marcas de tiempo	Permite detectar credenciales obsoletas
Método de rotación	Dos claves, alias de versión o ventana de mantenimiento	Evita cambios improvisados
Dependencias de revocación	Servicios que deben actualizarse primero	Protege la disponibilidad
Clasificación de los datos	Públicos, internos, confidenciales, regulados	Vincula la política de claves con la gobernanza de prompts

No incluyas el valor de la clave en el inventario. Almacena solo los metadatos y una referencia al secreto gestionado.

Separa las identidades por entorno, carga de trabajo y riesgo

El antipatrón más habitual es una única clave de producción compartida por todos los servicios. Resulta cómodo hasta que se filtra en un repositorio, un ejecutor de pruebas, el portátil de un contratista o una transcripción de soporte. Entonces el equipo no puede revocar la clave sin interrumpir otros productos.

Da preferencia a identidades separadas para:

• Producción, preproducción, desarrollo y pruebas locales.
• Tráfico de clientes, herramientas internas, trabajos por lotes y flujos de evaluación.
• Flujos de trabajo de alto riesgo que puedan llamar a herramientas o procesar datos confidenciales.
• Distintas unidades de negocio o tenants cuando los límites contractuales exijan separación.
• Acceso de emergencia, que debe permanecer desactivado o estrictamente controlado durante el funcionamiento normal.

Si un proveedor ofrece restricciones, aplícalas. Pueden incluir API, modelos, redes de origen, proyectos, referentes, aplicaciones o cuotas permitidos. Las directrices de Google Cloud sobre claves API, por ejemplo, recomiendan restringir las claves, aislarlas, eliminar las innecesarias, evitar incluirlas en commits de repositorios y supervisar su uso.

Si el proveedor no ofrece controles suficientemente detallados, aplícalos en tu propia pasarela. Una pasarela central puede validar la carga de trabajo que realiza la llamada, asignarle una ruta aprobada, aplicar presupuestos y límites de solicitudes, y mantener las credenciales de los proveedores detrás de un único límite en el servidor sometido a revisión. Consulta la guía de arquitectura de pasarelas de API de IA para ampliar la información sobre el diseño del enrutamiento y la conmutación por error.

Integra la gobernanza de prompts y registros en la gestión de claves

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

Antes de enrutar una solicitud, clasifica su contenido y aplica el principio de usar solo lo estrictamente necesario:

• Elimina credenciales, tokens, cookies, claves privadas y cadenas de conexión.
• Excluye los campos que el modelo no necesite.
• Tokeniza o seudonimiza los identificadores directos cuando la tarea pueda realizarse sin ellos.
• Rechaza datos regulados o sujetos a restricciones contractuales cuyo tratamiento no esté admitido.
• Separa las instrucciones del sistema del contenido de usuarios o de fuentes recuperadas que no sea de confianza.
• Valida los argumentos de las herramientas antes de que un agente pueda llamar a sistemas externos.

Los registros necesitan un esquema explícito. No confíes en que los desarrolladores recuerden que no deben registrar un objeto de solicitud. Define los campos permitidos y después descarta o transforma todo lo demás.

Un evento útil en producción 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"
}

Por defecto, no debe contener la cabecera de autorización, la clave del proveedor en bruto, el prompt completo, el documento cargado, argumentos de herramientas sin ocultar ni la respuesta completa del modelo. Si es necesario capturar el contenido para una evaluación o un incidente bajo controles estrictos, limita la captura en el tiempo, controla el acceso y sepárala de forma visible de la telemetría habitual.

La guía de registro de eventos de OWASP ofrece una base útil para excluir tokens de acceso, contraseñas, claves de cifrado y otros datos sensibles de los registros de las aplicaciones.

Diseña una rotación de claves API sin interrupciones

La rotación solo funciona como control si puede realizarse de forma segura. Un procedimiento que provoque una caída se pospondrá hasta que haya una emergencia.

Usa una secuencia con dos claves o secretos versionados cuando el proveedor permita que varias credenciales coexistan:

1. Crea una nueva clave del proveedor. Aplica las mismas restricciones que a la anterior o unas más estrictas.
2. Almacénala como una nueva versión del secreto. No sobrescribas el valor anterior si tu plataforma admite versiones o alias.
3. Despliega los componentes que deban leer la nueva versión. Actualiza la pasarela o las cargas de trabajo para que resuelvan el alias o la versión actuales.
4. Migra el tráfico y observa. Confirma las solicitudes correctas, los modelos esperados, el gasto, los límites de solicitudes y las tasas de error con la nueva versión de la clave.
5. Retira los consumidores de la clave anterior. Revisa los inventarios de despliegues, los trabajos, los procesos de trabajo y los entornos de recuperación ante desastres.
6. Revoca la clave anterior. No te limites a dejar de usarla; invalídala en el proveedor.
7. Verifica el rechazo. Una prueba controlada debe confirmar que la credencial anterior ya no funciona.
8. Registra las evidencias. Guarda las marcas de tiempo, los responsables, las cargas de trabajo afectadas, los resultados de validación y la fecha de la próxima revisión.

En un sistema que permita seleccionar la versión de la clave, la aplicación debe hacer referencia a un alias estable en lugar de fijar una versión del secreto en el código:

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 imprimas value, no serialices el objeto devuelto ni lo adjuntes a un error. Registra únicamente el identificador de versión que no contiene el secreto.

La guía de gestión de secretos de OWASP recomienda planificar todo el ciclo de vida del secreto, incluidas su creación, rotación, revocación, caducidad, auditoría, copia de seguridad y acceso de emergencia. También destaca la conveniencia de automatizar la rotación cuando sea viable.

Evita que los secretos lleguen a los repositorios y a los registros de CI

Los gestores de secretos no sirven de ayuda una vez que una credencial se ha copiado en el código fuente, datos de prueba, un artefacto de compilación o la salida de CI.

Aplica controles en tres etapas:

Antes del commit

• Proporciona archivos .env.example con marcadores de posición, nunca con credenciales válidas.
• Mantén los archivos locales de secretos fuera del control de versiones.
• Ejecuta un detector rápido de secretos en los hooks previos al commit para identificar patrones habituales de proveedores y valores de alta entropía.
• Enseña a los desarrolladores que eliminar un secreto en un commit posterior no lo borra del historial.

Durante los envíos y las solicitudes de incorporación de cambios

• Activa la detección de secretos y la protección de los envíos en los repositorios donde estén disponibles.
• Añade patrones personalizados para los tokens internos de la pasarela que los detectores públicos no reconozcan.
• Exige un motivo documentado para cada excepción y remítelas a una revisión de seguridad.
• Analiza los archivos generados, los notebooks, las instantáneas de pruebas y los planes de infraestructura, además del código fuente de la aplicación.

GitHub documenta la protección de los envíos como una forma de analizar el contenido durante el envío y bloquear los secretos detectados antes de que entren en un repositorio. La detección no justifica conservar la clave: considera expuesta cualquier credencial cuya inclusión en un commit se haya confirmado y rótala.

Durante CI/CD

• Prioriza las identidades de carga de trabajo o la federación de corta duración frente a las credenciales de nube almacenadas.
• Expón cada secreto únicamente al trabajo y al paso que lo necesiten.
• Enmascara los valores de secretos conocidos, pero no dependas del enmascaramiento como control principal.
• Desactiva el trazado del shell durante la recuperación de secretos.
• Impide que el código no fiable de repositorios bifurcados acceda a los secretos de despliegue.
• Revisa artefactos, cachés, volcados de fallos e informes de pruebas para detectar capturas accidentales.

Supervisa el uso sin registrar el secreto

Una buena supervisión permite responder a «¿quién usó qué permisos?» sin registrar la credencial que los concede.

Haz seguimiento de:

• Carga de trabajo, entorno, tenant o proyecto y versión de la clave.
• Proveedor, modelo, política de rutas y ruta alternativa.
• Número de solicitudes, volumen de tokens, gasto, latencia y categoría de error.
• Red de origen o identidad del despliegue cuando resulte ú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, una ubicación geográfica, un modelo o una franja horaria inesperados.

Configura alertas basadas en el comportamiento, además del gasto total. Una clave robada con un presupuesto reducido también puede exponer prompts o permitir explorar flujos de trabajo internos. A su vez, un trabajo por lotes legítimo puede provocar un pico de gasto sin que se hayan comprometido las credenciales. Correlaciona el uso del proveedor con los ID de solicitud de la aplicación, las decisiones de política de la pasarela, los eventos de despliegue y los registros de auditoría del gestor de secretos.

Para los controles de tráfico que complementan los controles de credenciales, consulta la guía de límites de solicitudes de LLM y el manual de enrutamiento alternativo de API de LLM.

Mide el tiempo desde la exposición hasta la revocación en los incidentes

Cuando una clave puede haber quedado expuesta, el primer objetivo es contener el incidente, sin esperar a demostrar si un atacante la ha utilizado.

Sigue esta secuencia:

1. Declara sospechosa la credencial. Registra cuándo y dónde puede haber quedado expuesta.
2. Crea una sustituta mediante el procedimiento controlado habitual. No pegues una nueva clave en el chat para agilizar la respuesta al incidente.
3. Migra las cargas de trabajo legítimas a la sustituta. Usa el procedimiento de rotación preparado.
4. Revoca la clave sospechosa. Si una revocación inmediata causaría un perjuicio inaceptable, aísla las rutas y reduce los límites mientras completas la migración.
5. Busca en todos los lugares donde pueda haber 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 notebooks, la configuración local y las copias de seguridad.
6. Revisa las vías de acceso a datos autorizadas. Determina a qué prompts, respuestas, archivos, herramientas o modelos podía acceder la clave, además de su alcance de facturación.
7. Correlaciona la actividad. Compara el uso del proveedor, los registros de la pasarela, los despliegues, las lecturas de secretos y la actividad de los usuarios.
8. Notifica a los responsables pertinentes. Involucra a los equipos de seguridad, plataforma, asesoría jurídica, privacidad y atención al cliente según los datos y contratos afectados.
9. Elimina la causa raíz. Añade el detector, la restricción, el límite entre identidades o el filtro de registros que faltaba.
10. Mide los tiempos. Registra el tiempo hasta la detección, la sustitución, la migración del tráfico, la revocación y la verificación.

La métrica que más suele ayudar a actuar es el tiempo desde la exposición hasta la revocación: cuánto tiempo sigue siendo utilizable una credencial sospechosa después de que la organización disponga de indicios fiables de exposición. Reducir ese intervalo exige responsables definidos de antemano, un inventario, automatización y una rotación probada, en lugar de un documento de políticas más largo.

Si emites claves API para tus propios clientes

Muchos productos de IA también entregan claves, por ejemplo, para que los clientes puedan llamar a tu agente o integrar tu funcionalidad. Las mismas buenas prácticas se aplican en sentido inverso:

• Genera las claves con un generador aleatorio criptográficamente seguro, con al menos 32 bytes de entropía.
• Añade un prefijo reconocible (como sk-fk- en las claves de Flatkey) para que los detectores de secretos y tu equipo de soporte puedan identificar las claves filtradas. El programa de socios de GitHub utiliza formatos de token conocidos para avisar a los emisores cuando se envía una clave a un repositorio público (detección de secretos de GitHub).
• Muestra la clave completa una sola vez y después almacena únicamente un hash. Si tu base de datos se filtra, las claves seguirán protegidas.
• Muestra solo un prefijo enmascarado en tu panel, junto con la fecha de creación y la del último uso.
• Haz que la revocación sea inmediata y devuelve 401 para las claves revocadas.
• Permite que los clientes limiten el alcance de las claves a modelos, proyectos o límites de gasto específicos.

Python: generar claves, calcular su hash y verificarlas

import hashlib
import hmac
import secrets

PREFIX = "sk-acme-"

def new_api_key() -> tuple[str, str]:
    """Return (plaintext key shown to the user once, hash to store)."""
    key = PREFIX + secrets.token_urlsafe(32)  # 32 random bytes
    return key, hashlib.sha256(key.encode()).hexdigest()

def verify(presented: str, stored_hash: str) -> bool:
    candidate = hashlib.sha256(presented.encode()).hexdigest()
    return hmac.compare_digest(candidate, stored_hash)  # constant-time compare

key, digest = new_api_key()
print(key[:12] + "...")   # show the full key once in the UI, never log it
print(verify(key, digest))  # True

Un hash rápido como SHA-256 es aceptable en este caso porque la clave es larga y aleatoria, a diferencia de una contraseña elegida por una persona. Almacena el hash, un ID de clave, el propietario, el alcance de los permisos y las marcas de tiempo.

Node.js: cargar una clave desde el entorno y denegar el acceso en caso de fallo

// Never fall back to a hardcoded default key.
const apiKey = process.env.FLATKEY_API_KEY;
if (!apiKey || !apiKey.startsWith("sk-fk-")) {
  throw new Error("FLATKEY_API_KEY is missing or malformed");
}

const res = await fetch("https://router.flatkey.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-haiku-5-5",
    messages: [{ role: "user", content: "ping" }],
    max_tokens: 5,
  }),
});
console.log(res.status); // log the status, never the header

Verifica que una clave revocada realmente haya dejado de funcionar

La revocación solo queda demostrada cuando la clave anterior falla. Después de cada rotación o incidente, ejecuta una comprobación como esta desde un equipo de confianza:

# Expect 401 for the revoked key; do not echo the key itself
OLD_KEY="$(cat /run/secrets/old_flatkey_key)"
status=$(curl -s -o /dev/null -w "%{http_code}" \
  https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $OLD_KEY")
if [ "$status" = "401" ]; then echo "revoked OK"; else echo "STILL ACTIVE: $status"; fi

Anota el resultado y la hora en el registro de rotación. Flatkey documenta que la revocación es inmediata y que cualquier solicitud con una clave revocada recibe 401 Unauthorized, sin periodo de gracia (documentación de claves API de Flatkey).

Cómo facilita Flatkey estas buenas prácticas

Flatkey te ofrece un único endpoint compatible con OpenAI (https://router.flatkey.ai/v1) para muchos proveedores de modelos, lo que reduce el número de claves de proveedores repartidas entre tus servicios. Según la documentación de claves API de Flatkey (consultada el 27 de octubre de 2026):

• Puedes crear varias claves: una por entorno, aplicación o miembro del equipo, con nombres descriptivos como prod-customer-chatbot.
• La clave sk-fk- completa solo se muestra una vez. Después, la página de claves muestra el nombre, la fecha de creación, la marca de tiempo del último uso y un prefijo enmascarado.
• La revocación es inmediata, por lo que debes desplegar la clave sustituta antes de revocar la anterior.
• Todas las claves comparten el saldo de la cuenta y pueden acceder a todos los modelos por defecto. Usa Groups en la consola para restringir una clave a modelos específicos o establecer una cuota de gasto.

La documentación de uso describe registros por solicitud con el modelo, los tokens, el coste y la clave, además de un límite de gasto mensual y alertas por correo electrónico cuando el saldo es bajo, que cubren las prácticas 10 y 11. Para organizaciones más grandes, la documentación de Flatkey para empresas describe subclaves organizadas en árbol con sus propios presupuestos y listas de modelos permitidos. Una pasarela no sustituye tu propia autenticación de clientes, la clasificación de datos ni las buenas prácticas de registro, así que mantén el resto de esta lista de verificación. Para empezar, consulta la guía inicial de integración de Flatkey.

Arquitectura de referencia para productos de IA con varios proveedores

Una configuración segura con varios proveedores puede organizarse en cinco capas:

1. Capa de identidad del cliente: autentica al usuario, dispositivo, agente o aplicación sin exponer las credenciales de los proveedores.
2. Capa de autorización de la aplicación: verifica los derechos de uso del producto, los límites entre tenants, el acceso a funcionalidades y los presupuestos.
3. Capa de políticas de datos: clasifica y oculta datos sensibles en prompts, archivos, contexto recuperado y argumentos de herramientas.
4. Capa de pasarela y enrutamiento: selecciona modelos aprobados, aplica cuotas, registra la atribución sin secretos y gestiona la conmutación por error.
5. Capa de credenciales de proveedores: almacena las credenciales de cada proveedor de forma aislada, rota las versiones y las expone solo a la carga de trabajo de enrutamiento de confianza.

Este diseño limita el alcance del 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 el acceso a todos los entornos. Un fallo en los registros no debería exponer tanto el secreto como el contenido completo.

Lista de verificación para producción

Usa esta lista antes del lanzamiento y durante las revisiones trimestrales de controles.

Custodia e identidad

• [ ] No se distribuye ninguna clave de proveedor de larga duración en el código de navegador, móvil, escritorio o extensiones.
• [ ] Cada carga de trabajo de producción tiene un responsable identificable y una vía definida de acceso a credenciales.
• [ ] Los accesos de producción, preproducción, desarrollo, evaluación y uso local están separados.
• [ ] Las claves compartidas entre personas se han sustituido por identidades de carga de trabajo o de pasarela siempre que ha sido posible.
• [ ] Las restricciones del proveedor y de la pasarela tienen el alcance más limitado que resulta viable.

Almacenamiento y entrega

• [ ] La fuente de referencia es un almacén de secretos gestionado o una vinculación de despliegue controlada.
• [ ] Las aplicaciones recuperan los secretos solo en tiempo de ejecución y no los imprimen ni serializan.
• [ ] Los trabajos de CI reciben únicamente los secretos necesarios para el paso correspondiente.
• [ ] Se auditan el acceso a los secretos y los cambios administrativos.
• [ ] El acceso de emergencia está documentado, limitado en el tiempo y probado.

Datos y observabilidad

• [ ] Las cabeceras de autorización y los valores de las claves se excluyen de registros, trazas, errores y exportaciones de soporte.
• [ ] El registro de prompts, respuestas, archivos y argumentos de herramientas sigue un esquema de campos permitidos.
• [ ] La ocultación de datos sensibles se realiza antes del enrutamiento entre proveedores.
• [ ] El uso puede atribuirse a una carga de trabajo, un entorno, una ruta, un proveedor, un modelo y una versión de clave.
• [ ] Las alertas abarcan rutas e identidades inusuales, además del gasto.

Rotación y respuesta

• [ ] Existe un procedimiento probado de rotación con dos claves o secretos versionados.
• [ ] Las claves anteriores se revocan en el proveedor y se verifica que no puedan utilizarse.
• [ ] La detección de secretos y la protección de los envíos cubren los repositorios y los artefactos generados.
• [ ] Una posible filtración activa la contención inmediata sin esperar a pruebas de abuso.
• [ ] El tiempo desde la exposición hasta la revocación se mide después de simulacros e incidentes.

Preguntas frecuentes

¿Cuáles son las buenas prácticas para gestionar claves API?

Mantén las claves fuera del código fuente y de las aplicaciones cliente, usa una clave distinta por entorno y carga de trabajo, restringe cada clave a las API, los modelos y el presupuesto que necesita, almacénalas en un gestor de secretos, rótalas según un calendario probado, elimina las que no se usen, activa la detección de secretos, no registres nunca claves y revócalas inmediatamente si sospechas una filtración.

¿Conviene almacenar una clave API en una variable de entorno?

Las variables de entorno son una forma razonable de entregar una clave a un proceso, pero no constituyen un sistema de gestión. El valor debe proceder de un gestor de secretos o del mecanismo de inyección de secretos de tu plataforma, con control de acceso, rotación y auditoría. No incluyas nunca archivos .env en los commits.

¿Con qué frecuencia deben rotarse las claves API?

Elige un intervalo según el riesgo y los controles de tu proveedor; muchos equipos rotan las claves de IA de producción cada 90 días y las rotan inmediatamente tras cambios de personal o una posible exposición. Lo más importante es ensayar la rotación, revocar la clave anterior y verificar la revocación.

¿Puede un navegador o una aplicación móvil llamar directamente a un proveedor de IA con una clave API?

Evítalo. Cualquier elemento distribuido a un dispositivo puede extraerse. Haz que el cliente se autentique en tu backend y deja que el backend o la pasarela llame al modelo con una clave en el servidor y límites por usuario.

¿Qué debo hacer si se filtra una clave API en GitHub?

Considérala comprometida. Crea una sustituta, migra las cargas de trabajo a ella, revoca la clave filtrada, confirma que devuelve 401, revisa el uso durante el periodo de exposición y añade detección de secretos o protección de los envíos para que no vuelva a ocurrir. Eliminar el commit no hace que la clave vuelva a ser segura.

¿Es más segura una sola clave de pasarela que muchas claves de proveedores?

Reduce el número de secretos en tu código, pero concentra los permisos. Usa claves de pasarela distintas por entorno y carga de trabajo, limita su alcance con restricciones de modelos y gasto, y protege las claves de proveedores detrás de la pasarela con el mismo cuidado que antes.

¿Cómo debo almacenar las claves API que emito para mis propios usuarios?

Almacena solo un hash de cada clave, muestra la clave completa una sola vez al crearla, muestra después un prefijo enmascarado y permite la revocación inmediata.

Fuentes y lecturas adicionales

• Guía de gestión de secretos de OWASP
• Guía de registro de eventos de OWASP
• GitHub: Acerca de la detección de secretos
• GitHub: Acerca de la protección de los envíos
• Google Cloud: Buenas prácticas para gestionar claves API
• Flatkey: Crear y gestionar claves API

Guías relacionadas de Flatkey: política de ocultación de datos sensibles en API de IA, arquitectura de pasarelas de API de IA y explicación de los límites de solicitudes de LLM.