Use Management API

The Control-Plane REST API is served by the API service on port 3000. Management routes are registered under /v1 and are protected by admin authentication.

Health and Diagnostics

Method	Path	Purpose
`GET`	`/health`	Liveness check.
`GET`	`/ready`	Dependency and service readiness.
`GET`	`/metrics`	Service metrics.
`GET`	`/docs`	Optional API docs when enabled.

Core Resources

Resource	Collection	Item	Extra
Zones	`GET`, `POST /v1/zones`	`GET`, `PATCH`, `DELETE /v1/zones/:id`	`GET /v1/zones/:id/dcr-status`
Applications	`GET`, `POST /v1/zones/:zoneId/applications`	`GET`, `PATCH`, `DELETE /v1/zones/:zoneId/applications/:id`	`POST /v1/zones/:zoneId/applications/dcr`
Providers	`GET`, `POST /v1/zones/:zoneId/providers`	`GET`, `PATCH`, `DELETE /v1/zones/:zoneId/providers/:id`	—
Resources	`GET`, `POST /v1/zones/:zoneId/resources`	`GET`, `PATCH`, `DELETE /v1/zones/:zoneId/resources/:id`	—

Policy and Access

Area	Read	Write
Policy validation	—	`POST /v1/policies/validate`
Policies	`GET /v1/zones/:zoneId/policies`, `GET /v1/zones/:zoneId/policies/:id`	`POST /v1/zones/:zoneId/policies`, `POST /v1/zones/:zoneId/policies/:id/versions`, `DELETE /v1/zones/:zoneId/policies/:id`
Policy sets	`GET /v1/zones/:zoneId/policy-sets`, `GET /v1/zones/:zoneId/policy-sets/:id`, `GET /v1/zones/:zoneId/policy-sets/:id/versions/:versionId`, `GET /v1/zones/:zoneId/policy-sets/:id/activation-status`	`POST /v1/zones/:zoneId/policy-sets`, `POST /v1/zones/:zoneId/policy-sets/:id/versions`, `POST /v1/zones/:zoneId/policy-sets/:id/activate`, `POST /v1/zones/:zoneId/policy-sets/:id/simulate`, `DELETE /v1/zones/:zoneId/policy-sets/:id`
Policy templates	`GET /v1/policy-templates`	—
Grants	`GET /v1/zones/:zoneId/grants`, `GET /v1/zones/:zoneId/grants/:id`	`POST /v1/zones/:zoneId/grants`, `DELETE /v1/zones/:zoneId/grants/:id`
Provider grants	—	`POST /v1/zones/:zoneId/provider-grants`, `POST /v1/zones/:zoneId/provider-grants/oauth/authorize`, `POST /v1/zones/:zoneId/provider-grants/revoke`

Use Console when you are performing these operations interactively. Use the Admin SDK or Control API when automation needs the same management behavior.

Audit, Sessions, and Step-Up

Resource	Methods and paths
Audit	`GET /v1/zones/:zoneId/audit`, `GET /v1/zones/:zoneId/audit/by-request/:requestId`, `GET /v1/zones/:zoneId/audit/by-request/:requestId/explain`
Admin audit	`GET /v1/zones/:zoneId/admin-audit`
Sessions	`GET /v1/zones/:zoneId/sessions`
Agent sessions	`GET /v1/zones/:zoneId/agent-sessions` (filter by `status`, `lifecycle`, `label`, `parent_id`, `application_id`; `format=csv` to export)
Step-up challenges	`GET /v1/zones/:zoneId/step-up-challenges`, `GET /v1/zones/:zoneId/step-up-challenges/:id`, `POST /v1/zones/:zoneId/step-up-challenges/:id/satisfy`
Zone events	Zone-scoped event routes under `/v1/zones/:zoneId/...`

Usage Notes

Use Console for human workflows and Admin SDK or Control API for automation.
For scoped, non-interactive provisioning, drive the Control API with a control key. See Automate Management and the controlBootstrap example.
Prefer declarative reconciliation over scripting individual writes: Declarative Management converges a zone from a desired-state document with idempotent apply, dry-run plan, and CI-friendly verify.
Policy activation and simulation are API operations, but top-level caracal runtime commands do not expose them.
Writes that produce downstream state changes enqueue signed Redis stream events through the API outbox.

Next Step

Continue to Use Coordinator API when automation needs agent session, invocation, or delegation endpoints.