--- title: "Glossary" url: "https://docs.caracal.run/v1.0/reference/glossary/" markdown_url: "https://docs.caracal.run/markdown/v1.0/reference/glossary.md" description: "Canonical Caracal terms and names used across the documentation." page_type: "reference" concepts: [] requires: [] --- # Glossary Canonical URL: https://docs.caracal.run/v1.0/reference/glossary/ Markdown URL: https://docs.caracal.run/markdown/v1.0/reference/glossary.md Description: Canonical Caracal terms and names used across the documentation. Page type: reference Concepts: none Requires: none --- 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](/v1.0/reference/errors/) when a service, SDK, Gateway, or verifier returns a machine-readable error.