Caracal Mental Model

Caracal answers one question: should this principal or agent receive scoped authority for this resource right now?

It answers that question during token exchange, records the decision, and returns a mandate only when the active policy set allows the request.

flowchart TD
  Zone["Zone"] --> App["Application"]
  Zone --> Resource["Resource"]
  Zone --> PolicySet["Active policy set"]
  App --> Session["Session"]
  Session --> Exchange["Token exchange"]
  Resource --> Exchange
  PolicySet --> Exchange
  Exchange -->|"allow"| Mandate["Mandate"]
  Exchange -->|"deny / step-up"| Audit["Audit event"]
  Mandate --> Audit

Six Core Nouns

Noun	What it means
Zone	The tenant boundary for configuration, signing keys, policy, sessions, and audit.
Application	A registered client, service, or agent workload.
Principal	The acting identity, such as a user, service, or agent.
Resource	The protected target: API, MCP server, tool group, or upstream service.
Policy	Rego logic that evaluates the requested exchange.
Mandate	The short-lived JWT that proves authority to a Gateway or connector.

Most of these are configured directly. A grant is a permission binding for resource scopes that policy can read during evaluation; it is not the mandate a resource server verifies.

One Application, Many Agents

An application and an agent are different layers, and they scale differently:

• An application is the credentialed security boundary — operator-provisioned or dynamically registered, holding the secret Caracal authenticates. It is created deliberately.
• An agent session is the runtime unit — created the moment a workload acts, with no secret and no registration step.

One application backs many agent sessions. A durable workload registers one managed application, then spawns, delegates, and fans out as many agent sessions as it needs under that single credential. You do not create an application per agent; per-agent attribution comes from the agent session, not a new application. See Should I create one application per agent?.

Three Runtime Verbs

Verb	Meaning
Exchange	Ask the STS to convert existing identity into a resource mandate.
Spawn	Open an agent session derived from a subject session.
Delegate	Pass constrained authority from one agent session to another.

One Decision Point

The STS is the decision point. It evaluates the active policy set with the principal, session, resource, scopes, grant, delegation edge, and step-up context. If policy allows the request, the STS signs a mandate. If policy denies the request, no mandate is issued.

Resource servers still verify mandates locally through the Gateway or connectors. That keeps every request protected even after token exchange succeeds.

Why This Model Matters

• Long-lived provider secrets stay out of agents.
• Authority expires quickly and can be revoked.
• Delegation carries typed constraints instead of informal trust.
• Every allow, deny, step-up, and revocation path is auditable.

Next, read Authority and Enforcement to see where each enforcement layer fits.