Usar la API

3 min de lectura

La API te permite integrar Kujira con tus propios sistemas, automatizaciones y agentes. Sirve tanto para consultar el estado de la organización como para operar los recursos para los que hayas concedido permiso.

Antes de empezar

1. Crea un token de servicio desde el panel.
2. Concédele únicamente los permisos que necesita tu integración.
3. Envíalo en cada petición mediante la cabecera Authorization.

El token identifica una única organización. Puedes obtener su identificador con una primera consulta:

curl "https://api.kujira.so/v1/org?page=1&limit=20" \
  -H "Authorization: Bearer $KUJIRA_TOKEN"

La respuesta incluye las organizaciones disponibles en data. Con un token de servicio habrá una sola; usa su id en las rutas que contienen {org_id}.

{
  "data": [{ "id": 42, "name": "Acme Inc" }],
  "total": 1,
  "page": 1,
  "limit": 20
}

Cada token pertenece a una única organización. No puede ver ni operar otra, aunque conozca su identificador.

La API evoluciona

La API está en desarrollo activo. Podemos añadir, modificar o retirar rutas, campos y permisos a medida que evoluciona Kujira. Antes de automatizar un flujo crítico, consulta el contrato publicado y revisa los cambios cuando actualices tu integración.

El contrato publicado es la fuente de referencia

La referencia de la API se genera a partir de una copia sincronizada del contrato OpenAPI. Cada endpoint indica su método, ruta, datos de entrada, respuesta y permiso necesario.

El contrato público contiene la superficie soportada para integraciones. Las rutas internas del panel no forman parte de él y no deben usarse como una API alternativa.

Para importar o comprobar el contrato que publica la plataforma en ese momento, usa

OpenAPI JSON actual.

La copia de esta documentación,

OpenAPI JSON de la documentación,

es útil para trabajar con la versión que estás leyendo o revisar cambios en un pull request.

Compatibilidad

Para una integración crítica, valida las rutas, parámetros y respuestas contra el contrato publicado. No dependas de campos que no aparezcan en él ni de detalles de implementación del panel.

• Usa los operationId para identificar operaciones en clientes generados o pruebas de integración.
• Ramifica por el code de los errores, no por el texto de message.
• Guarda una copia del contrato con el que probaste tu integración y compárala con el contrato actual antes de actualizarla.

Diseña integraciones seguras

• Crea un token por integración y nómbralo según su función.
• Da el mínimo alcance posible: un agente que solo lee auditoría necesita audit.view, no acceso total.
• Guarda el token en un gestor de secretos, nunca en código, capturas o mensajes.
• Configura caducidad y una lista de IP permitidas cuando puedas acotar el entorno desde el que se conectará.
• Trata un error 403 como falta de permiso y un 404 como un recurso fuera del alcance del token o inexistente.

Puedes revocar un token al instante desde Tokens de servicio. Sus acciones quedan anotadas en el Registro de actividad.

Para agentes y herramientas externas

Un agente de programación, un flujo de automatización o una herramienta externa puede usar el mismo contrato. Entrégale un token limitado y describe la tarea que debe resolver; por ejemplo, consultar alertas, revisar auditoría o mantener agentes concretos. El token marca exactamente hasta dónde puede llegar, independientemente de qué software lo utilice.

Referencia de endpoints

Consulta el método, los parámetros, las respuestas y el permiso que exige cada operación.

Tokens de servicio

Crea, limita, revisa y revoca las credenciales de tus integraciones.