Version: 1.0.0

API de Kadu

API multi-tenant para la orquestación de agentes.

Autenticación

Toda ruta exige Authorization: Bearer <token>, donde el token es un access token RS256 emitido por el Authorization Server de Kobana (Cuenta Kobana) para el recurso kadu. Kadu solo verifica el token, con las claves públicas que publica el AS; no emite tokens. La organización es el claim org.

Alcances

Los alcances se exigen en toda ruta, excepto GET /v1/me. Cada solicitud exige un único nivel de acceso, y un nivel nunca sustituye a otro:

Nivel	Concede
read	lectura (GET)
write	creación y modificación (POST, PATCH, PUT) — y lectura
delete	eliminación (DELETE)
import	importación masiva (ningún endpoint hoy)
export	exportación masiva (ningún endpoint hoy)
all	todos los niveles anteriores

Un token con alcances kadu/{recurso} (ej.: kadu/tasks) queda restringido a esos recursos, y el nivel vale solo dentro de ellos; kadu/all alcanza todos los recursos. El recurso de una ruta es el primer segmento después de /v1 (/executions/{id}/logs → executions). Recursos: activities, environments, executions, files, memberships, memories, organizations, repository, roles, schedules, secrets, system_events, tasks, todos, usage, users, webhook_deliveries, webhooks, workspaces.

Permisos del usuario

Además de los alcances, un token emitido para una persona (con email) queda limitado a su rol en la organización (Role.permissions): cada ruta exige agent.<recurso>.<acción> (list, read, create, update, delete, y las acciones executions.run, webhook_deliveries.replay y repository.sync), con los comodines *, agent.* y agent.<recurso>.*. Un rol que no lo concede responde 403 USER_PERMISSION_DENIED (details.required); una persona sin vínculo con la organización, 403 NOT_A_MEMBER. Un token de integración, sin persona, vale solo por los alcances. GET /v1/me no verifica el rol.

Permisos de la organización

Las rutas de lanzamiento, logs, webhooks, entregas, entornos, secrets, programaciones, endpoint de la Task, repositorio y uso respetan también las habilitaciones que Kobana da a la organización para las pantallas de la consola. Una operación no habilitada responde 403 FEATURE_NOT_ENABLED, con details.permission.

Un token sin ningún alcance que Kadu reconozca no alcanza nada más allá de /me. Un alcance insuficiente responde 403 INSUFFICIENT_SCOPE, con details.required (los niveles que bastarían).

Contrato

• Wire en snake_case; los mapas libres (custom_metadata, payload, parameters…) son opacos.
• Los valores monetarios y de costo son number (USD en *_usd, reales en *_brl).
• Éxito: { data } o { data, meta }; error: { error: { code, message, details? } } con code en UPPER_SNAKE.
• Listados por cursor: cursor + limit (máx. 100), ordenación por sort_by + sort_order; meta: { next_cursor, limit }.
• X-Idempotency-Key en todo POST/PUT/PATCH (24h por organización).
• Cuerpo de POST/PUT/PATCH de hasta 1 MiB; por encima de eso, 413 PAYLOAD_TOO_LARGE.