Understand the Model

Read this section after Get Started when you need to design an integration or explain a decision. Get Started gave you the working vocabulary - application, resource, policy, mandate, Gateway, audit, zone. This section completes the model with the pieces behind them: how a Session bounds one run, how an optional Subject adds end-user attribution, how a Delegation narrows authority between Sessions, and how revocation and audit tie it all together. One sentence holds the whole picture: an Application acts in a Zone, a Session bounds execution, Delegation narrows authority, policy approves a Resource request, and a Mandate carries the result.

Read This Section in Order

Start here	Use it to understand
Caracal Mental Model	The smallest useful picture of Caracal.
Authority and Enforcement	Where decisions happen before requests reach a target.
Zones	The tenant boundary that owns keys, policies, resources, sessions, and audit.
Identities and Applications	Application credentials, Subjects and Federated users, Authority records, and Sessions.
Resources and Grants	What can be accessed and which scopes are granted.
Providers	The credential Caracal attaches to the upstream target.
Policies and Policy Sets	Rego rules evaluated by the STS during token exchange.
Mandates	The short-lived JWT that carries approved authority.
Approvals	How sensitive actions are held for a human decision.
Session Delegation	How one agent passes bounded authority to another.
Delegation Constraints	The limits attached to delegated authority.
Sessions and Revocation	How active authority is ended and propagated.
Audit and Request Traces	The event trail behind decisions and runs.
Caracal Operator	An optional governed assistant for reviewed console changes.

Core Flow

flowchart LR
  App["Application"] --> Session["Session"]
  Subject["Federated user (optional)"] -. attribution .-> Session
  Session --> SDK["SDK / Gateway request"]
  SDK --> STS["STS token exchange"]
  STS --> Policy["Active policy set"]
  Policy --> Mandate["Mandate JWT"]
  Mandate --> Gateway["Gateway or adapter"]
  Gateway --> Resource["Protected resource"]
  STS --> Audit["Audit ledger"]
  Gateway --> Audit

The same model appears across the product:

• Onboarding uses the web console guided setup to create the first zone, application, provider, resource, and policy, then makes the first protected call with the application’s identity through an SDK transport.
• Guides use the SDKs, web console, Admin API, and adapters to build repeatable integrations.
• Operations pages use the same terms when explaining keys, revocation, audit, and runtime health.

Term Map

Term	Short definition	Canonical page
Zone	Tenant boundary for authority data and signing keys.	Zones
Application	Registered client or agent workload.	Identities and Applications
Subject	The identity work is done for: the Application itself by default, or a Federated user for attribution and supported approval flows.	Identities and Applications
Authority record	Immutable record of identity and authority context created by an exchange.	Identities and Applications
Resource	Protected API, MCP server, tool group, or upstream target.	Resources and Grants
Grant	Policy data that describes which Application roles may request Resource scopes.	Resources and Grants
Provider	Credential mode Caracal uses toward the upstream target.	Providers
Policy	Versioned Rego logic evaluated at token exchange.	Policies and Policy Sets
Policy set	Versioned bundle of policies activated for a zone.	Policies and Policy Sets
Mandate	Short-lived JWT issued by the STS after policy approval.	Mandates
Delegation	Bounded authority transfer between Sessions.	Session Delegation
Revocation anchor	Authority record ID, Root authority record ID, Session ID, or Delegation ID checked by resource servers.	Sessions and Revocation
Caracal Operator	Governed natural-language assistant that turns intent into reviewed control-plane changes.	Caracal Operator
System zone	Reserved caracal.sys/ zone for the infrastructure that runs Caracal.	Zones

What to Read Next

After the concepts, use Guides for task-focused procedures or SDKs for language-specific reference.