Understand the Model

Caracal gives agents short-lived, policy-approved authority instead of long-lived secrets. Read this section after your first integration when you need the vocabulary behind guides, SDKs, operations pages, and API reference material.

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	The identities that authenticate, run, and delegate.
Resources and Grants	What can be accessed and which scopes are granted.
Policies and Policy Sets	Rego rules evaluated by the STS during token exchange.
Step-Up Challenges	How sensitive actions require fresh approval.
Mandates	The short-lived JWT that carries approved authority.
Agent 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	The governed natural-language assistant for control-plane changes.

Core Flow

flowchart LR
  Principal["Principal or agent"] --> SDK["SDK / Gateway request"]
  SDK --> STS["STS token exchange"]
  STS --> Policy["Active policy set"]
  Policy --> Mandate["Mandate JWT"]
  Mandate --> Gateway["Gateway or connector"]
  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, resource, and policy, then you configure runtime access with environment variables or a caracal.toml profile.
• Guides use the SDKs, Console, Admin API, and connectors 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
Principal	User, service, or agent identity bound to a session.	Identities and Applications
Resource	Protected API, MCP server, tool group, or upstream target.	Resources and Grants
Grant	Binding from an application and user to resource scopes.	Resources and Grants
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 edge	Bounded authority transfer between agent sessions.	Agent Delegation
Revocation anchor	Session, root session, agent session, or delegation edge 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.