---
title: What Caracal Does
description: Gateway-first access control, credential brokering, audit, and revocation for AI agents.
pageType: concept
---

Caracal lets you run agents with scoped, traceable, revocable authority without putting provider secrets in agent code. This page explains the default product path, the few supported alternatives, and what is future direction.

## The core problem

AI agents and autonomous workflows need access to tools, APIs, and data. Giving them long-lived credentials causes two problems: you cannot know what the agent will do with them before it acts, and you cannot revoke access granularly once something goes wrong.

Caracal addresses both problems by giving the agent a short-lived, scoped Caracal access token only after policy allows the requested action. The token expires quickly, can be revoked by multiple authority anchors, and never contains provider-native credentials.

## The authority-plane model

Caracal's product model is small: an **agent app** starts an **agent run**, asks for a **mandate**, uses it against a **resource**, and may grant a narrower **delegated permission** to another run. The reference model underneath those names is principal, execution session, mandate, resource, delegation edge, policy decision, and audit event.

The system issues authority, narrows it, traces it, and revokes it. Gateway routing, SDK context propagation, MCP helpers, and provider credential brokering are implementation surfaces that preserve that model at execution boundaries.

Caracal is not trying to wrap every provider SDK, scheduler, prompt router, or protocol abstraction. If an integration path cannot preserve mandate verification, revocation, policy context, and audit, it should stay outside the core authority plane until it has a clear enforcement boundary.

## The golden path

The default path is:

```text
agent app
  → Caracal SDK opens an agent run
  → agent calls the Gateway
  → public STS issues only Caracal access tokens
  → internal broker resolves provider credentials for the Gateway
  → Gateway forwards the upstream call
  → audit records the decision and action result
```

This is the path new integrations should use. It gives the strongest default security boundary: agents never see provider OAuth tokens or API keys, the Gateway checks revocation before and during requests, and every proxied action has an execution audit event.

## The enforcement point

The public STS issues short-lived Caracal access tokens. It does not return provider-native credentials to agent-facing callers. Before signing a token, it:

1. Receives an exchange request carrying the agent identity and requested tool/provider resource.
2. Loads the active policy set for the zone.
3. Evaluates OPA with the agent, resource, requested scopes, session state, delegation state, and trace context.
4. Signs a token only when policy returns `decision = "allow"` and `evaluation_status = "complete"`.
5. Emits an authorization audit event for every resource decision.

If no policy set is active in the zone, the STS installs a deny-all fallback — no agent can exchange credentials until a policy is activated. There is no default-allow state.

## The Gateway

When an agent calls a tool, MCP server, REST API, or provider endpoint through the Gateway, the Gateway:

1. Verifies the Caracal token signature against the zone key.
2. Checks replay and revocation anchors.
3. Resolves the provider route for the requested resource.
4. Calls the internal broker path when provider credentials are needed.
5. Substitutes the provider OAuth token or API key only on the upstream request.
6. Emits an action execution audit event with status, latency, result class, auth mode, and revocation interruption state.

The agent presents a Caracal access token; the Gateway handles the credential the upstream expects.

## Delegation

An agent can grant a narrower delegated permission to another agent. The invariant is:

```text
source = delegator
target = receiver
receiver uses the delegated permission
```

Parenthood alone does not grant access. Each delegated permission narrows authority through explicit scope, resource, TTL, hop, and policy constraints. The source cannot use the receiver's delegated permission, unrelated agents cannot use it, and revocation terminates downstream authority.

Delegation is a same-zone runtime contract. Cross-zone federation and cross-zone delegation are deliberately not part of the current model; the priority is making same-zone authority issuance, narrowing, tracing, and revocation excellent before adding federation semantics.

## The audit ledger

Every authorization decision produces an append-only audit event. Gateway-proxied calls also produce action execution audit events. Together they answer:

- Was the call allowed or denied?
- Which policy and template version determined the outcome?
- Which agent run and delegated permission were involved?
- Which provider route and auth mode were used?
- Did the upstream call succeed, fail, or stop because revocation arrived?

Nothing is ever updated or deleted in the audit table. Query the trail through the TUI and CLI (`audit tail`, `explain`).

## What this is not

Caracal does not replace your LLM framework, agent scheduler, or prompt router. It sits alongside those systems as the access-control and audit boundary. Caracal does not inspect or filter tool-call content; it enforces whether the call may happen, which credential is used, how it is audited, and how quickly it can be revoked.

## Provider flow patterns

Use the Gateway path by default. The full product surface collapses into four patterns:

| Pattern | Status | Enforcement meaning |
| --- | --- | --- |
| Gateway-mediated HTTP | Implemented default | Gateway verifies the mandate, checks replay and revocation, brokers provider credentials, proxies the call, and writes action-result audit. |
| Connector-verified service/tool | Supported pattern | Your service or tool verifies mandates, replay, revocation, and result audit itself. Use this when you own the boundary. |
| Application-managed external provider call | Supported attribution pattern | Your application calls the provider directly and attaches Caracal context for traceability. The provider call is not Caracal-enforced unless your code performs the same checks. |
| Native broker plugins | Future direction | A plugin contract may later move provider-specific credential brokering behind a native Caracal boundary. This is not current runtime behavior. |

Connector and application-managed paths are not production boundaries merely because a package exists. They are production boundaries only when mandate verification, replay protection, revocation checks, and action-result audit are implemented end to end.

## Status labels

The docs use these labels intentionally:

| Label | Meaning |
| --- | --- |
| Implemented behavior | Runtime behavior available in the OSS stack. |
| Supported pattern | A documented path with a clear enforcement contract that operators can adopt when they meet the requirements. |
| Example-only pattern | Demo or sample-app code that illustrates usage but is not a production integration contract. |
| Future direction | Product direction that is not current runtime behavior. |

## Next step

Read [Installation](./installation/) to install the CLI and bring up the stack, or skip to [Key Ideas at a Glance](./key-ideas/) for the simplified mental model.
