Kadu API
Multi-tenant API for agent orchestration.
Authentication​
Every route requires Authorization: Bearer <token>, where the token is an RS256 access token issued by Kobana's Authorization Server (Kobana Account) for the kadu resource. Kadu only verifies the token, using the public keys the AS publishes; it does not issue tokens. The organization is the org claim.
Scopes​
Scopes are required on every route, except GET /v1/me. Each request requires a single access level, and one level never substitutes for another:
| Level | Grants |
|---|---|
read | read (GET) |
write | create and update (POST, PATCH, PUT) — and read |
delete | removal (DELETE) |
import | bulk import (no endpoint today) |
export | bulk export (no endpoint today) |
all | all of the levels above |
A token with kadu/{resource} scopes (e.g. kadu/tasks) is restricted to those resources, and the level applies only within them; kadu/all reaches every resource. A route's resource is the first segment after /v1 (/executions/{id}/logs → executions). Resources: activities, environments, executions, files, memberships, memories, organizations, repository, roles, schedules, secrets, system_events, tasks, todos, usage, users, webhook_deliveries, webhooks, workspaces.
User permissions​
Besides scopes, a token issued for a person (with email) is limited to their role in the organization (Role.permissions): each route requires agent.<resource>.<action> (list, read, create, update, delete, and the actions executions.run, webhook_deliveries.replay and repository.sync), with the wildcards *, agent.* and agent.<resource>.*. A role that does not grant it responds 403 USER_PERMISSION_DENIED (details.required); a person with no membership in the organization gets 403 NOT_A_MEMBER. An integration token, with no person, is governed by scopes only. GET /v1/me does not check the role.
Organization permissions​
The routes for run, logs, webhooks, deliveries, environments, secrets, schedules, Task endpoint, repository and usage also respect the permissions Kobana grants the organization for the console screens. An operation that is not enabled responds 403 FEATURE_NOT_ENABLED, with details.permission.
A token with no scope that Kadu recognizes reaches nothing beyond /me. Insufficient scope responds 403 INSUFFICIENT_SCOPE, with details.required (the levels that would suffice).
Contract​
- Wire in
snake_case; free-form maps (custom_metadata,payload,parameters…) are opaque. - Monetary and cost values are
number(USD in*_usd, reais in*_brl). - Success:
{ data }or{ data, meta }; error:{ error: { code, message, details? } }withcodein UPPER_SNAKE. - Cursor-based listings:
cursor+limit(max. 100), ordering bysort_by+sort_order;meta: { next_cursor, limit }. X-Idempotency-Keyon everyPOST/PUT/PATCH(24h per organization).POST/PUT/PATCHbody up to 1 MiB; above that,413 PAYLOAD_TOO_LARGE.