API architecture
Separate the supported customer read API from runtime ingestion, managed component protocols, dashboard internals, and planned contracts.
AgentKeeper has several HTTP surfaces with different callers and trust models. Only the API-key routes in the generated endpoint reference are the supported customer read API.
Contract boundaries
| Lane | Caller | Purpose | Customer contract |
|---|---|---|---|
| Customer read API | Customer automation with an organization API key | Read key context, baseline policy, setup health, limited recent decisions, and eligible telemetry summaries | Published in the OpenAPI reference |
| Runtime integration API | AgentKeeper hooks, Gateway, collectors, and supported custom integrations | Request a decision or send normalized runtime evidence | Documented separately and scoped to runtime components |
| Managed component protocols | Signed devices, packages, browser extensions, and policy resolvers | Enrollment, policy distribution, heartbeat, and managed coverage | AgentKeeper-managed implementation path, not a custom integration starting point |
| Dashboard internals | Signed-in AgentKeeper browser session | Power the product UI | Not a public automation contract and intentionally absent from OpenAPI |
| Planned data and management APIs | Future service accounts | Historical export and configuration automation | Not shipped; see Roadmap |
Authentication
| Credential | Use | Boundary |
|---|---|---|
| Organization API key | Published read endpoints and approved runtime integrations | Organization-scoped; not a general dashboard or administration token |
| Device credential or signed-device headers | Installed managed components | Issued through enrollment and bound to the component or device |
| Signed-in dashboard session | Product UI | Browser and role model only; do not use for headless automation |
Validate /api/v1/me before an automation reads other resources. API-key owner
context is not workstation attribution: runtime sources must still report the
supported host, user, source, and session evidence.
Enforcement boundary
An API route can participate in blocking only when the caller receives the decision before execution and honors it. The runtime evaluation and MCP evaluation paths can do this for supported hooks and routed calls. Audit, heartbeat, OTLP, provider export, and post-tool paths cannot undo completed activity.
Some runtime decision endpoints return HTTP 200 with a blocking verdict
because agent runtimes may treat non-200 responses as hook failure. Consumers
must validate the documented response body instead of inferring the decision
from HTTP status alone.
Public-reference rule
Do not add a dashboard route to OpenAPI merely because the browser can call it. A public route needs a stable authentication model, scopes, request and response schemas, pagination or limits, error behavior, and a stated compatibility policy. Until then, use the dashboard or a tenant-specific agreement.