Uso de claves API

Una clave API es una credencial para que una integración de servidor se autentique en las rutas API disponibles de CatalogIQOS sin usar la sesión interactiva de una persona. Actualmente sirve para lecturas autorizadas de pistas y solicitudes de trabajos en segundo plano.

Cada clave pertenece al espacio activo donde se creó. Sus solicitudes solo pueden acceder a registros de catálogos del mismo espacio. CatalogIQOS ofrece rutas limitadas y versionadas, no una API pública completa. No todos los permisos visibles corresponden hoy a un endpoint para clientes.

Solo los administradores del espacio pueden listar, crear o revocar claves. La clave pertenece al espacio, aunque el administrador creador queda registrado y se usa como identidad creadora de los trabajos enviados con ella.

1. Abre Configuración del espacio y selecciona Claves API.
2. Escribe un nombre que identifique la integración o el entorno.
3. Selecciona una fecha futura de vencimiento o déjala vacía.
4. Selecciona al menos un permiso y concede solo lo indispensable.
5. Crea la clave, cópiala de inmediato y guárdala en un gestor de secretos del servidor.

La credencial sin procesar se muestra una sola vez. CatalogIQOS conserva un hash SHA-256 y un prefijo corto, no el secreto recuperable. Si pierdes la clave, revócala y crea otra. El formato es ciq_<prefijo hexadecimal de 8 caracteres>_<secreto>.

Una clave con fecha de vencimiento deja de autenticarse después de ese momento. Revocar registra una fecha de revocación y bloquea usos posteriores; no elimina silenciosamente el registro. Revoca de inmediato credenciales comprometidas, retiradas o innecesarias.

Los permisos son controles acumulativos, no prueba de que exista un endpoint. Aplica siempre el principio de privilegio mínimo.

La ruta base es /api/v1 en tu despliegue. Envía la clave mediante el encabezado Authorization con el esquema Bearer:

Authorization: Bearer ciq_<prefijo>_<secreto>

• GET /api/v1/tracks requiere tracks:read y admite catalogId, search y limit.
• GET /api/v1/tracks/{trackId} requiere tracks:read y limita la pista al espacio de la clave.
• POST /api/v1/jobs requiere jobs:create; el tipo puede exigir otro permiso y los identificadores se validan contra el espacio.

curl "https://TU-HOST-CATALOGIQOS/api/v1/tracks?limit=25" \
  -H "Authorization: Bearer $CATALOGIQOS_API_KEY"

No existe todavía un contrato OpenAPI completo ni un catálogo público más amplio. Confirma los payloads de trabajos con tu contacto de implementación antes de crear una integración de producción.

• Trata las claves API como contraseñas.
• Nunca las confirmes en el control de versiones.
• Nunca las expongas en código del navegador o del cliente.
• Guárdalas en variables de entorno del servidor o en un gestor de secretos.
• Usa solo los permisos necesarios.
• Prefiere vencimiento y rotación periódica.
• Usa claves separadas por integración y entorno.
• Revoca inmediatamente cualquier credencial comprometida.
• No incluyas secretos en registros, solicitudes de soporte, capturas o analítica.

La autenticación compartida es PARCIAL; las tres rutas la invocan, pero no existe middleware global. El aislamiento por espacio, vencimiento, revocación, hash, autorización de las tres rutas y versionado /api/v1 están IMPLEMENTADOS. La aplicación de permisos es PARCIAL. El registro de auditoría de claves y solicitudes y la limitación de frecuencia NO ESTÁN IMPLEMENTADOS. Los contratos públicos estables son PARCIALES porque no existe una especificación OpenAPI completa.

Por estas brechas, CatalogIQOS debe describirse como acceso limitado a la API empresarial, no como una API general completamente preparada para producción.

API key required indica que falta el encabezado o no usa Bearer. Invalid API key puede indicar formato o secreto incorrecto, vencimiento o revocación. Insufficient API key scope significa que la clave es válida pero no tiene el permiso requerido. Una pista o catálogo puede aparecer como no encontrado si pertenece a otro espacio.

Consulta Roles y permisos para el acceso administrativo y Perfil del espacio para la identidad y configuración del espacio. Actualmente no existe un artículo separado con una referencia completa de la API empresarial.