Use the Admin API

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

This is the supported HTTP surface for trusted automation. Prefer Admin Package for typed pagination and errors. Never expose an admin token to an agent, browser, or protected upstream.

Authentication

Send an admin token as a bearer credential on every /v1 request:

Authorization: Bearer <admin token>

Status	Error	Meaning
401	unauthorized, invalid_admin_token	Token is missing, malformed, expired, or revoked.
403	admin_token_read_only	Write attempted with a read-only token.
403	admin_token_zone_mismatch, zone_forbidden	Token is scoped to a different zone.
403	system_zone_read_only	Write attempted against the reserved system zone.

Error Shape

Every non-2xx /v1 response carries a single JSON envelope:

{
  "error": "invalid_body",
  "error_description": "Request body failed validation",
  "details": { "issues": [{ "path": ["name"], "message": "Required" }] }
}

error is the stable machine code to branch on. error_description, when present, is a human-readable summary of the failure. details, when present, carries structured context: for example, the validation issues on invalid_body, the failed connectivity check on provider_check_failed, or the live dynamic-client count on dcr_shutdown_required. See Error Codes for the shared code catalog.

Malformed JSON, unknown fields in strict schemas, wrong types, missing required values, invalid identifiers, and zone mismatches are rejected before mutation. Success status depends on the operation: reads and updates return 200, creates commonly return 201, asynchronous policy activation returns 202, and deletes commonly return 204. Treat each endpoint response as authoritative rather than assuming every write returns an object.

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, GET /v1/zones/:id/overview
Applications	GET, POST /v1/zones/:zoneId/applications	GET, PATCH, DELETE /v1/zones/:zoneId/applications/:id	POST /v1/zones/:zoneId/applications/dcr, POST /v1/zones/:zoneId/applications/:id/rotate-secret, GET /v1/zones/:zoneId/applications/:id/client-secret
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	-
Workloads	GET, POST /v1/zones/:zoneId/workloads	GET, PUT, DELETE /v1/zones/:zoneId/workloads/:id	POST /v1/zones/:zoneId/workloads/:id/rotate-secret, GET /v1/zones/:zoneId/workloads/:id/secret

Workloads are the launcher identities caracal run uses. Create a workload, deliver its secret to the launch environment, and rotate the secret here when you automate runtime setup; the secret stays retrievable from Secret Store custody through an audited reveal endpoint.

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
Federated user issuers	GET /v1/zones/:zoneId/subject-issuers, GET /v1/zones/:zoneId/subject-issuers/:id	POST /v1/zones/:zoneId/subject-issuers, PATCH /v1/zones/:zoneId/subject-issuers/:id, DELETE /v1/zones/:zoneId/subject-issuers/:id
Provider connections	GET /v1/zones/:zoneId/provider-connections, GET /v1/zones/:zoneId/provider-connections/oauth/callback (OAuth redirect target)	POST /v1/zones/:zoneId/provider-connections, POST /v1/zones/:zoneId/provider-connections/oauth/authorize, POST /v1/zones/:zoneId/provider-connections/revoke

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

Audit, Authority Records, Sessions, and Approvals

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
Authority records	GET /v1/zones/:zoneId/authority-records. Filter by authority_record_id, subject_id, status, or kind (user for Federated users, application for application Subjects); use format=csv to export. Rows carry federated_user_issuer only when the Subject is a Federated user.
Subjects	GET /v1/zones/:zoneId/subjects, GET /v1/zones/:zoneId/subjects/overview?subject_id=, POST /v1/zones/:zoneId/subjects/revoke (the kill switch revokes every live Authority record for the Subject, terminates linked Sessions, revokes Delegations and provider connections, and feeds the revocation stream)
Sessions	GET /v1/zones/:zoneId/sessions. Filter by status, lifecycle, label, parent_session_id, application_id, or subject_id; use format=csv to export. Rows resolve subject attribution (subject_authority_record_id, subject_id) and carry federated_user_id and federated_user_issuer only when the Session acts for a Federated user.
Approvals	GET /v1/zones/:zoneId/approvals, GET /v1/zones/:zoneId/approvals/counts, GET /v1/zones/:zoneId/approvals/:id, POST /v1/zones/:zoneId/approvals/:id/approve, POST /v1/zones/:zoneId/approvals/:id/reject.

Platform Administration

These routes require the global admin token.

Resource	Methods and paths
Admin tokens	GET, POST /v1/admin-tokens; DELETE /v1/admin-tokens/:id
Audit retention	GET, PUT /v1/audit-retention

Use POST /v1/admin-tokens to mint read-only or zone-scoped tokens for automation, and keep the bootstrap token as break-glass.

Listing and Filters

• List endpoints accept limit (default 200, max 500) and an opaque cursor. Every list response is an envelope of items and next_cursor; pass next_cursor as the next request’s cursor and stop when it is null. The Admin SDK list helpers for collection resources drain the cursor chain and return the complete collection.
• GET /v1/zones/:zoneId/audit accepts since, until, request_id, decision, event_type, application_id, session_id, authority_record_id, and label.
• Add format=csv to audit and admin-audit lists for exports; use fields to select columns.

The cursor is opaque: do not parse, edit, or reuse it with different filters. Ordering is service-defined and stable only within the cursor chain.

curl -s -H "Authorization: Bearer $CARACAL_ADMIN_TOKEN" \
  "http://localhost:3000/v1/zones/$CARACAL_ZONE_ID/resources?limit=100"

{ "items": [...], "next_cursor": null }

Idempotency and Retries

Admin writes do not expose a universal Idempotency-Key contract. Do not blindly retry a timed-out create, rotate, approve, revoke, or delete request. Read the object back, or use the Admin SDK ensure* reconcilers for declarative provisioning. GET/HEAD calls are safe to retry subject to normal rate limits. A 429 response can include Retry-After.

Credential create, rotation, and reveal endpoints are security-sensitive. Plaintext secret responses must be delivered directly to the target secret store and excluded from logs, traces, and retry payload capture. Reveals are audited.

Usage Notes

• Use the web 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 the supported Control management model and Bootstrap Control State.
• Prefer declarative reconciliation over scripting individual writes. Control’s state plan|verify|apply workflows converge a Zone from desired state with dry-run and CI-friendly verification.
• Policy activation and simulation are API operations, but top-level caracal runtime commands do not expose them.
• Caracal Operator routes under /v1/operator and zone-scoped operator paths back the web console. They are not a stable automation surface.
• 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 Session, invocation, or Delegation endpoints.

Related Pages

• Admin Package
• Manage Product Objects
• Manage Product State