Concepts

Caracal is built around a small set of concepts that compose cleanly. Understanding them in order gives you a working mental model of the whole system before touching any code.

Reading order

The concepts below build on each other. Read the Authority Model first — it explains why the other concepts exist. Then read them in the order they appear in the sidebar.

Concept	One-line definition
Authority Model	The decision contract that governs every token exchange
Mandate	The short-lived, signed credential issued after a policy allows exchange
Policy	The Rego document that decides whether exchange is permitted
Principal and Application	Who is making the request
Zone	The tenancy boundary that owns keys, policies, and resources
Resource and Grant	What agents can access and who is permitted to access it
Delegation Graph	How authority passes from one agent to another
Caveats and Constraints	Limits attached to delegation edges
Sessions and Revocation	Agent session lifecycle and how authority is withdrawn
Audit Ledger	The tamper-evident record of every decision
Step-Up Challenge	How policies require elevated proof before granting access

Terminology precision

The docs use these terms with strict meaning throughout:

• Mandate — the JWT issued by the STS. Other systems call this an “access token.” Caracal calls it a mandate because it is explicitly authorized by policy before issuance.
• Principal — the actor making a request. In practice, always an Application.
• Zone — the tenancy boundary. Never synonymous with “environment” or “region.”
• Policy — a Rego document registered in Caracal. Not to be confused with IAM policies from other systems.
• Session — an agent session tracked by the Coordinator. Distinct from a user HTTP session.