Múltiples Claves API por Endpoint

Gigantics soporta asignar múltiples claves API a un solo endpoint, permitiendo escenarios de gestión de acceso sofisticados incluyendo rotación de claves sin tiempo de inactividad, control de acceso multi-partido y migración gradual de credenciales.

Resumen

Cada endpoint de API puede estar asociado con múltiples claves API. Cuando llega una solicitud, el sistema valida la clave proporcionada contra todas las claves asignadas hasta encontrar una coincidencia. Esto significa que cualquiera de las claves asignadas puede autenticar el mismo endpoint, proporcionando flexibilidad en cómo gestionas y distribuyes credenciales.

┌────────────────────────────────────────────────────────────┐
│ API Endpoint: /api/org/proj/model/1/dataset/42             │
├────────────────────────────────────────────────────────────┤
│ Claves API Asignadas:                                      │
│   • api-key-production-2024                               │
│   • api-key-backup-2024                                   │
│   • api-key-migration-temp                                │
└────────────────────────────────────────────────────────────┘
         │
         │ Cualquiera de estas claves autentica
         ▼
┌────────────────────────────────────────────────────────────┐
│ Solicitud con x-api-key: api-key-production-2024           │
│ → ✓ Autenticado                                            │
└────────────────────────────────────────────────────────────┘

Interfaz de Usuario

Asignando Múltiples Claves

Cuando asignas claves API a un endpoint de conjunto de datos o pipeline, verás un modal de selección que permite elegir múltiples claves:

Comportamiento de Asignación Rápida

Cuando tienes solo una clave API disponible en tu proyecto, el sistema la asigna automáticamente sin mostrar el modal. Esto agiliza el flujo de trabajo para configuraciones más simples.

Gestión de Selección

• Agregando claves: Haz clic en "Asignar" en cualquier clave no seleccionada para agregarla al endpoint actual
• Removiendo claves: Haz clic en "Asignado" en una clave seleccionada para removerla
• Selección múltiple: Puedes seleccionar tantas claves como necesites antes de confirmar

Flujo de Autenticación

Cuando una solicitud llega a un endpoint, el middleware de autenticación realiza la siguiente validación:

1. Extrae la clave: Lee la clave API de cualquiera de los dos:

   • Parámetro de consulta: ?api_key=tu-clave-aqui
   • Cabecera Authorization: Authorization: Bearer tu-clave-aqui

2. Carga endpoint: Recupera la configuración del endpoint desde la base de datos

3. Itera a través de claves asignadas: Para cada clave en el array apiKeys:

   • Carga el registro de clave desde la base de datos
   • Omite si la clave no existe
   • Omite si la clave está inactiva (isActive: false)
   • Compara la clave proporcionada contra el hash almacenado usando bcrypt
   • Si se encuentra coincidencia, la autenticación tiene éxito

4. Retorna resultado: Si alguna clave coincide, la solicitud se autentica. Si ninguna coincide, se retorna un error 403.

Casos de Uso

Rotación de Claves Sin Tiempo de Inactividad

Rota claves de producción sin interrumpir el servicio:

1. Paso 1: Crea una nueva clave API con un propósito descriptivo (ej., "Clave de Producción 2025")
2. Paso 2: Asigna tanto la clave antigua como la nueva al endpoint
3. Paso 3: Actualiza tus clientes para usar la nueva clave
4. Paso 4: Monitorea el uso para confirmar que todos los clientes han migrado
5. Paso 5: Remueve la clave antigua del endpoint

Durante el período de transición, ambas claves funcionan simultáneamente, asegurando que no haya interrupción del servicio.

Control de Acceso Multi-Partido

Proporciona diferentes claves a distintos consumidores para mejor seguimiento y revocación:

• Socio A recibe api-key-partner-a-2024
• Socio B recibe api-key-partner-b-2024
• Equipo Interno recibe api-key-internal-service

Todas las claves funcionan con el mismo endpoint, pero puedes:

• Rastrear qué socio realizó qué solicitudes (a través de los registros de uso)
• Revocar el acceso individual sin afectar a los demás
• Configurar diferentes límites de tasa o políticas de acceso por clave (si está configurado)

Migración Gradual

Cuando migras de un sistema de autenticación a otro:

1. Asigna tanto la clave heredada como la nueva estructura de clave
2. Migra gradualmente a los clientes al nuevo formato
3. Elimina la clave heredada una vez completada la migración

Claves de Acceso de Respaldo

Mantén una clave de respaldo que se usa raramente pero está disponible si la clave principal se ve comprometida:

• Clave principal: Usada por todos los sistemas de producción
• Clave de respaldo: Guardada de forma segura, solo usada en emergencias

Si la clave principal se ve comprometida, puedes revocarla inmediatamente mientras la clave de respaldo continúa ofreciendo acceso hasta que se emita una nueva clave principal.

Mejores prácticas

Convenciones de Nombres para Claves

Usa propósitos descriptivos al crear claves:

• Clave de Producción 2024-Q4
• Clave de Acceso de Respaldo
• Integración de Socio - Acme Corp
• Migración Temporal - 2025-01

Esto facilita identificar las claves en el modal de selección y gestionarlas con el tiempo.

Gestión del Ciclo de Vida de Claves

1. Antes de la rotación: Crea la nueva clave y asigna tanto la antigua como la nueva
2. Durante la rotación: Monitorea qué claves se están usando via registros de API
3. Después de la rotación: Elimina rápidamente las claves no usadas para reducir la superficie de ataque

Consideraciones de Seguridad

• Claves mínimas: Solo asigna tantas claves como sea necesario. Más claves suponen más vectores de ataque
• Auditorías regulares: Revisa periódicamente qué claves están asignadas a cada endpoint
• Seguimiento del propósito: Usa propósitos descriptivos para recordar por qué existe cada clave
• Claves inactivas: Desactiva las claves no usadas en lugar de eliminarlas inmediatamente, en caso de que necesites auditar usos pasados

Monitoreo de Uso

Todas las llamadas a la API generan entradas de trabajo que incluyen la clave API usada. Usa estos registros para:

• Rastrear qué claves están activas
• Identificar claves que deberían rotarse
• Detectar patrones de uso no autorizados
• Planificar calendarios de rotación basados en uso real

Integración con Control de Acceso

Múltiples claves API funcionan sin problemas con el control de acceso basado en roles de Gigantics:

• Usuarios con permiso ManageAPIKeys pueden asignar múltiples claves
• Cada clave debe ser creada dentro del mismo proyecto que el endpoint
• La rotación de claves no afecta los permisos de roles en la UI
• El acceso API vía claves es independiente de los roles de usuario en la UI

Para más detalles, consulta Control de Acceso.

Documentación Relacionada

• Asignación de Endpoint API - Aprende a crear y gestionar endpoints
• Autenticación - Entiende cómo funciona la autenticación API
• Control de Acceso - Revisa los permisos basados en roles para la gestión de API