Zones

A zone is the main isolation boundary in Caracal. It groups the configuration and runtime state needed to decide, issue, verify, revoke, and audit authority.

What a Zone Owns

Area	Zone-owned data
Identity	Applications, credentials, subject sessions, and agent sessions.
Authorization	Resources, providers, grants, policies, policy sets, and step-up challenges.
Cryptography	Zone signing keys and JWKS used to verify mandates.
Delegation	Delegation edges, constraints, depth limits, and cascade revocation state.
Audit	Decision events, diagnostics, request IDs, and explain traces.

Why Zones Exist

Zones let teams run separate environments, tenants, or trust domains without mixing authority data.

Common zone boundaries include:

production, staging, and development environments;
separate customers in a hosted deployment;
isolated product areas with different policy owners;
high-sensitivity resources that need distinct keys and audit trails.

When several boundaries could apply at once, use Model Your Application in Caracal to choose between a separate zone, a shared zone with separate resources, and a customer attribute in policy input. To serve many of your own customers from one zone, follow Serve Your Own Customers.

Zone Lifecycle

flowchart LR
  Create["Create zone"] --> Register["Register applications and resources"]
  Register --> Policy["Author and activate policy set"]
  Policy --> Run["Issue mandates and run agents"]
  Run --> Audit["Review audit and explain traces"]
  Audit --> Tune["Update grants, policy, and resources"]
  Tune --> Run

Zone setup is normally managed through the web console. The Admin API exposes the same objects for automation.

Key and Policy Isolation

Each zone has its own signing-key and JWKS context. Resource servers verify mandates against the issuer, audience, and expected zone. Policy activation is also zone-scoped: activating a policy set in one zone does not affect another zone.

Dynamic Client Registration

A zone gates whether workloads may self-register short-lived DCR applications. DCR is off by default; an operator turns it on per zone (dcr_enabled). While enabled, a control-plane workload holding an admin token can mint auto-expiring application identities through the zone DCR endpoint — Console never creates them.

Disabling DCR on a zone that still has live DCR applications requires an explicit decision, because turning the gate off does not by itself revoke identities already issued:

Choice	Effect
Keep live	Blocks new registrations; existing DCR applications stay valid until their own expiry.
Revoke live	Blocks new registrations and immediately archives live DCR applications, revoking their sessions and terminating related agent access.

The Console prompts for this choice when you disable DCR with live applications, and the Admin API takes the same decision through the dcr_shutdown field on a zone patch (zones.patch(id, { dcr_enabled: false, dcr_shutdown: 'keep_live' | 'revoke_live' })). Use zones.dcrStatus(id) to read the live DCR application count before deciding.

System Zone

Caracal reserves one system zone for the infrastructure that runs the platform itself, distinct from the tenant zones you create. It carries the reserved caracal.sys/ namespace and is provisioned by the bootstrap admin identity, so a tenant can never create, author, or impersonate the objects inside it.

The Caracal Operator self-governs through this zone: its reserved control identity, least-privilege control grants, and the providers and resources that route its model calls all live there. The Operator will not open a session in, or execute against, the system zone, so its delegated authority stays away from the infrastructure that runs Caracal. An administrator can also mark additional zones as system zones to place them out of the Operator’s reach.

Operational Guidance

Keep production and non-production authority in separate zones.
Name zones after the trust boundary, not a single service.
Keep resource identifiers stable because policies, grants, and audit traces refer to them.
Rotate zone signing keys using the operations workflow, then confirm resource servers load the current JWKS.

Next Step

Read Identities and Applications to understand who acts inside a zone.