Glossary

Use these terms consistently across docs, API names, web console labels, and examples.

Term	Meaning
Application	Registered client identity in a zone that software runs as; confidential applications hold a secret and can exchange credentials.
Authority record	One STS exchange record. Its Authority record ID anchors revocation, ancestry, and audit for authority minted by that exchange. Stored in the authority_records table.
Audit ledger	Append-only evidence stream and database records for decisions and operations.
Approval	A policy-raised hold that pauses a request until a human with authority approves or rejects it; surfaced on the web console Approvals page and returned on the wire as interaction_required. SDKs identify it as approvalId; the wire carries the same value as approval_id.
Caracal Operator	Governed natural-language console assistant that turns intent into reviewed, audited control-plane changes within your operator scope.
Confinement	Policy data (confinement) that caps every Session carrying a matching label prefix to a fixed scope set; it can only narrow authority.
Console	Browser-based management UI served by the packaged web tier in Compose and Helm; caracal web opens it during local development.
Control API	Optional authenticated automation surface for remote management dispatch, authorized by scoped control keys.
DCR application	Auto-expiring application created programmatically through Dynamic Client Registration for a separate temporary credential boundary; it binds to one task Session and is never created in the web console.
Delegation	Bounded authority one session grants to another: scopes, optional resource, constraints, and expiry, revocable independently. Stored internally as an edge in the delegation graph.
Delegation ID	Unique product identifier for a Delegation.
Federated user	One kind of Subject: an external end-user identity supplied by a trusted identity provider. Caracal never authenticates Federated users; it verifies their tokens against a registered Federated user issuer, then federates and records the identity verbatim for attribution, connections, approvals, and revocation.
Federated user issuer	Zone-registered trust declaration for an external identity system (issuer, JWKS URL, audience) whose end-user identity tokens the STS accepts to mint Federated users. The Admin API resource is subject-issuers.
Gateway	Reverse proxy that verifies inbound authority, exchanges with STS, and forwards to upstreams.
Grant	Access assignment for a resource. Policy grants data maps roles to allowed scopes per resource; managed delegated grants record Subject-level assignments and cascade revocation to the Subject’s sessions.
Guided setup	Web console checklist that walks a new zone through creating its first application, provider, resource, and active policy from live zone state.
Launch binding	Instruction on a Workload naming an environment variable, a resource, and scopes; at launch, caracal run injects that resource provider’s credential into the variable after a policy decision.
Managed application	Durable, operator-provisioned application identity for known software; created in the web console or Admin API and reused across many Sessions.
Mandate	Short-lived scoped access token (a JWT) carrying Caracal authority.
Mandate use	The use claim classifying a mandate: session (reusable lifecycle authority for Coordinator operations), gateway (single-use Gateway-ingress pass), or resource (what the Gateway’s own exchange hands the upstream path).
Policy	Rego content that participates in allow/deny decisions.
Policy set	Activated bundle of policy versions for a zone.
Principal	User, service, application, or session identity participating in authority.
Provider	Credential source that supplies what a protected upstream receives after Caracal approves a call.
Resource	Protected API, tool, MCP server, provider target, or upstream identifier. Use a stable resource:// URI such as resource://pipernet; the upstream URL can change without changing the identifier.
Restrict	Policy data (restrict) forming a deny overlay: any entry denies every exchange in the zone until it is removed.
Root authority record	Authority record at the root of an STS exchange ancestry chain. Its Root authority record ID is checked for revocation.
Runtime profile	caracal.toml or environment configuration used by SDK credential loaders.
Run manifest	Console-authored launch bindings served by STS to caracal run.
Scope	Named, action-oriented permission declared on a resource (for example pipernet:read); policies grant scopes and mandates carry them.
Session	Governed execution record the Coordinator holds while code runs under Caracal: it binds identity and delegated authority around whatever executes - an AI agent step, a job, a tool call - and anchors audit attribution. Started with the SDK session() (task, retired when the block exits) or startSession() (long-lived, heartbeat-leased, retired with close).
Session handle	Holder-owned handle for a long-lived Session started with startSession(); it renews the heartbeat lease and is retired explicitly.
Session ID	Unique product identifier for a governed Session.
STS	Security Token Service that performs token exchange and mandate issuance.
Subject	The identity work is done for: the JWT sub recorded on Authority records and mandates. Every exchange has a Subject of one of two kinds - the application itself (the default) or a Federated user. A Federated user’s identifier arrives verbatim from the exchanged token and is owned by the application’s own identity system.
Subject authority record ID	Authority record ID attached to a Session for Subject attribution and lifecycle. SDK fields name it subjectAuthorityRecordId, subject_authority_record_id, or SubjectAuthorityRecordID; attaching it does not by itself make later resource mandates carry the Federated user’s sub.
System zone	Reserved caracal.sys/ zone for the infrastructure that runs Caracal; the Operator self-governs through it and never executes against it.
Workload	Launcher identity for software started with caracal run; it holds a client secret and the launch bindings that name which credentials are injected.
Zone	Tenant and trust boundary for product state, policies, grants, sessions, and audit.

Naming Rules

• Use Caracal, not informal product nicknames.
• Use Application for the registered identity that authenticates to Caracal; use AI agent for the software acting under it. Authority always belongs to the Application - never write that an agent is registered, holds the credential, or is allowed by policy.
• Use Workload only for the Launcher identity consumed by caracal run; describe long-running software generically as a service or process.
• Use mandate for Caracal-issued JWT authority, not generic “token” when the distinction matters.
• Use Session and Session ID for governed Coordinator executions. Use Authority record, Authority record ID, and Root authority record ID for STS exchange records and ancestry.
• Use Subject only for the JWT sub identity. A Subject is not an Authority record or Session, and it is never only a federated identity: it is the application itself by default, or a Federated user.
• Use Federated user for the external end-user kind of Subject; avoid “optional subject”, “external subject”, and “subject from IdP”.
• Use canonical parsed claim names in application code; reserve raw JWT names for explicit protocol tables.
• Use subjectAuthorityRecordId, subject_authority_record_id, and SubjectAuthorityRecordID for the Subject authority record ID in SDK code.
• Use Delegation and Delegation ID in product surfaces; reserve delegation edge and delegation_edge_id for storage and raw protocol references.
• Use web console for the browser UI and Control API for automation.
• Use Admin API for the /v1 management REST surface; control plane describes the architecture layer, not an API name.
• Use top-level caracal only for runtime lifecycle, caracal run, and caracal web.

Next Step

Use Error Codes when a service, SDK, Gateway, or verifier returns a machine-readable error.