Use API Reference

Use this section when you need wire-level behavior. For task workflows, start in Guides. For service ownership and operations, use Understand Services and Operations.

Most integrations should use an SDK or the web console. Only the Admin API is a general external management API. Coordinator is a wire-facing SDK protocol, STS is an OAuth endpoint, Gateway is a protected reverse proxy, and event topics are deployment infrastructure rather than end-user HTTP APIs.

API Surfaces

Surface	Base	Purpose
Use the Admin API	API service /v1	Zones, applications, providers, resources, policies, policy sets, grants, Authority records, Sessions, audit, approvals, and templates.
Use Coordinator API	Coordinator service	Sessions, long-lived Session services, invocations, Delegations, and SDK lifecycle endpoints.
Use STS Endpoint	STS service	OAuth token exchange, JWKS, Approval status, and internal policy operations.
Proxy Through Gateway	Gateway service	Protected reverse-proxy behavior rather than CRUD endpoints.
Use Event Topics	Redis Streams	Audit, invalidation, revocation, Session, invocation, and Delegation topics.

Service Ports

Local Compose ports: API 3000, Coordinator 4000, STS 8080, Gateway 8081, Audit 9090; Control shares the API port when enabled. The canonical port and endpoint maps are in Defaults and Limits and Monitor Health and Metrics.

Error Shape

Caracal service errors use the shared OAuth-compatible shape:

{
  "error": "access_denied",
  "error_description": "policy denied request",
  "requestId": "018f..."
}

See Error Codes for canonical codes.

Do not assume one status code across surfaces: STS follows OAuth semantics, adapters distinguish 401 from 403, and Gateway can return either a Caracal preflight error or the upstream response. Branch on the documented machine-readable error field where a Caracal JSON error is present.

Stability

The public Admin /v1 routes and STS RFC 8693 exchange are supported integration surfaces. Coordinator field names such as agents, agent_session_id, and delegation_edge_id are protocol names retained for SDK interoperability; applications should use facade names. /internal/*, operator routes, private STS directives, and raw Redis topics are not general application APIs.

Reading Path

Need	Page
Manage product objects over HTTP	Use the Admin API
Manage Session and Delegation runtime state	Use Coordinator API
Exchange authority for mandates	Use STS Endpoint
Understand Gateway proxy requirements	Proxy Through Gateway
Consume or verify stream contracts	Use Event Topics

Next Step

Start with Use the Admin API when automating product setup.