Autenticación

Todos los endpoints de API requieren autenticación usando claves API. Gigantics soporta dos métodos para proporcionar la clave API con cada solicitud.

Métodos de Autenticación

Parámetro de Consulta

Incluye la clave API como un parámetro de consulta:

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=abc123xyz-def456uvw-ghi789rst"

Cabecera de Autorización

Incluye la clave API en la cabecera Authorization usando formato de token Bearer:

curl -H "Authorization: Bearer abc123xyz-def456uvw-ghi789rst" \
  "https://yourserver/api/org/proj/model/1/dataset/42"

Prioridad: Si se proporcionan ambos métodos, el parámetro de consulta tiene precedencia.

Formato de Clave API

Las claves API generadas por Gigantics siguen este formato:

{prefix}-{key}

Donde:

• prefix - 10 caracteres (usado para identificación en la UI)
• key - 21 caracteres
• Longitud total: 31 caracteres
• Formato: Caracteres alfanuméricos seguros para URL

Ejemplo: abc123xyz-def456uvw-ghi789rst

Proceso de Validación de Clave

Cuando una solicitud llega a un endpoint, el sistema:

1. Extrae la clave de cualquiera de los dos: parámetro de consulta o cabecera Authorization
2. Carga el endpoint de configuración desde la base de datos
3. Itera a través de las claves asignadas para ese endpoint:
   • Carga cada registro de clave API
   • Omite claves inactivas (isActive: false)
   • Compara la clave proporcionada contra el hash bcrypt almacenado
   • Se detiene en la primera coincidencia
4. Retorna resultado:
   • Si se encuentra una coincidencia → la solicitud se autentica
   • Si no hay coincidencia → retorna 403 Forbidden con mensaje "Unknown API key"

Múltiples Claves por Endpoint

Cuando múltiples claves API están asignadas a un endpoint, cualquiera de las claves asignadas autenticará la solicitud. Esto permite:

• Rotación de claves sin tiempo de inactividad
• Acceso multi-partido con diferentes claves
• Claves de respaldo para acceso de emergencia

El sistema verifica todas las claves asignadas hasta encontrar una coincidencia. Ver Múltiples Claves API por Endpoint para más detalles.

Seguridad de Claves

Almacenamiento

• Las claves API se almacenan como hashes bcrypt en la base de datos
• La clave en texto plano solo se muestra una vez durante la creación
• Las claves no se pueden recuperar después de la creación - deben regenerarse

Estados de Clave

• Activa (isActive: true) - La clave puede autenticar solicitudes
• Inactiva (isActive: false) - La clave está deshabilitada y no autenticará

Gestión de Claves

• Las claves pueden editarse para cambiar su propósito o estado activo
• Las claves pueden eliminarse, lo que revoca inmediatamente el acceso
• Eliminar una clave no elimina los endpoints - los endpoints solo pierden ese método de autenticación

Respuestas de Error

Clave Faltante

Estado: 403 Forbidden

Respuesta:

{
  "message": "Not authorized"
}

Clave Inválida

Estado: 403 Forbidden

Respuesta:

{
  "message": "Unknown API key"
}

Clave Inactiva

Estado: 403 Forbidden

Respuesta:

{
  "message": "Disabled API key"
}

Endpoint Desconocido

Estado: 403 Forbidden

Respuesta:

{
  "message": "Unknown API Endpoint"
}

Seguimiento de Uso

Cuando una solicitud se autentica exitosamente:

1. El contador calls del endpoint se incrementa
2. La marca de tiempo updatedAt de la clave API se actualiza
3. Estos datos son visibles en la UI:
   • Los conteos de llamadas de endpoint aparecen en la página de Claves API
   • El tiempo de último uso muestra cuándo se usó la clave por última vez

Mejores Prácticas

1. Nunca comprometas claves al control de versiones - Usa variables de entorno o gestores de secretos
2. Usa solo HTTPS - Las claves API enviadas por HTTP pueden ser interceptadas
3. Rota claves regularmente - Especialmente si una clave podría estar comprometida
4. Desactiva en lugar de eliminar - Al solucionar problemas, desactiva claves para poder reactivarlas sin recrear endpoints
5. Usa propósitos descriptivos - Nombra claves por su caso de uso (ej., "Dashboard de Producción", "Trabajo ETL")
6. Monitorea el uso - Verifica "Última llamada" y conteos de llamadas para detectar acceso no autorizado

Documentación Relacionada

• Asignación de Endpoints de API - Aprende cómo crear y asignar endpoints
• Múltiples Claves API por Endpoint - Entiende la asignación de múltiples claves
• Control de Acceso - Revisa permisos para gestionar claves API