The admin API

A copy, not the original

This page is docs/admin-api.md from the Onbe control plane repository, taken at commit d516e99 on 2026-09-16. The contract lives next to the code that implements it; this copy is generated, never edited here, and the build fails if the two drift apart.

The admin API manages agent registrations at /admin/agents. It is meant for operators and GitOps tooling, not for agents or end users.

Authentication in v0.1

Every admin request carries one shared API key as a bearer token:

Authorization: Bearer <Onbe:Admin:ApiKey>

The key is set with Onbe:Admin:ApiKey (environment variable Onbe__Admin__ApiKey) and must be at least 32 characters; generate it with openssl rand -base64 32. When it is not set the admin API is disabled and every /admin request answers 503. A missing or wrong key answers 401 and writes an admin.denied record to the audit ledger.

Proper admin identities and role-based access control are out of scope for v0.1. There is one key, it grants every admin operation, and rotating it means changing the setting and restarting.

Endpoints

Method	Path	Result
POST	/admin/agents	201 with the agent; 400 with per-field errors; 409 if the id exists
GET	/admin/agents	200 with every agent
GET	/admin/agents/{agent_id}	200 or 404
PATCH	/admin/agents/{agent_id}	200 with the merged agent; 400; 404
DELETE	/admin/agents/{agent_id}	204; 404; 409 while the agent still has tasks
DELETE	/admin/agents/{agent_id}/tasks	200 with {"revoked_tasks": n}; 404
DELETE	/admin/tasks/{task_id}	200 with {"revoked_tasks": n}; 404
GET	/audit	200 with one page of audit records; 400 with per-field errors

The POST body is the registration payload of the spec. The PATCH body is any subset of those fields plus enabled; the merged registration is validated as a whole. Every mutation writes agent.registered, agent.updated or agent.deleted to the audit ledger in the same transaction, so the ledger and the registry cannot disagree.

Disabling an agent ("enabled": false) takes effect on the next request: agents are read from storage per request and never cached.

Audit query

GET /audit is the query of spec section 7.2, behind the same key. Filter with any of sponsor, agent_id, task_id, from, to and decision; page with limit (default 100, at most 1000) and the next_cursor of the previous page passed as cursor. Records come back oldest first, each in the ledger’s own shape with the hashes as hex, so a page can be checked against audit-verify output. The query only reads; nothing about it is written to the ledger except a failed authentication.

Kill switches

DELETE /admin/tasks/{task_id} revokes the task, every task delegated from it at any depth, and every grant under them, with reason operator_kill_switch on the task named and parent_revoked on its descendants. DELETE /admin/agents/{agent_id}/tasks does the same for every live task of the agent. Both write one task.revoked record per task in the same transaction. Both are idempotent: a repeat answers 200 with revoked_tasks: 0 and writes nothing.

Tokens already issued stay valid until they expire, bounded by the agent’s max_token_ttl, unless the tool server calls introspection per request as it must for high_risk_audiences. Refreshing a revoked task fails at once with access_denied.