Resources and Grants

A resource is something Caracal protects. A grant is a configured permission binding that says an application and user may request specific scopes for that resource.

Resources

Resources describe protected targets such as:

HTTP APIs behind the Gateway;
MCP servers and tool groups;
internal services protected by Express, FastMCP, or net/http connectors;
provider-backed targets that need credential mediation.

Resource field	Purpose
Identifier	Stable policy and token audience target. Always use the `resource://<slug>` convention, such as `resource://pipernet`; keep it stable even when the upstream URL changes.
Upstream URL	Gateway forwarding target.
Scopes	Named Caracal resource actions that policies and mandates can constrain.
Gateway application	Managed application identity used by Gateway-mediated resources.
Upstream credential provider	Resource binding to the provider record used when Gateway attaches no credential, a Caracal mandate, OAuth tokens, API keys, or bearer tokens.

Grants

A grant binds:

a zone;
an application;
a user or subject;
a resource;
one or more scopes.

Grants are not the final decision. They are one input to policy. The active policy set can still deny, require step-up, or constrain the exchange.

Caracal expresses grants in two related forms. The platform decision contract reads grants as a policy data document in package caracal.authz, keyed by resource and mapping each role to its allowed scopes; see Policy for the exact shape. The control plane also stores managed delegated grants (the delegated_grants table, authored through the Admin or Control API) and provider grants (the provider_grants table, the per-subject upstream credential grants authored under Providers).

Exchange Relationship

flowchart LR
  App["Application"] --> Grant["Grant"]
  User["User / subject"] --> Grant
  Resource["Resource"] --> Grant
  Grant --> STS["STS policy input"]
  Policy["Active policy set"] --> STS
  STS -->|"allow"| Mandate["Mandate with resource and scopes"]

Scope Design

Prefer small, action-oriented scopes:

Good	Avoid
`payments:read`	`admin`
`tickets:comment`	`write_all`
`mcp:tool:call`	`tools`

Use resource identifiers for targets and scopes for actions. Do not encode environment, tenant, or user identity into scope names when those belong in the zone, principal, or policy input.

Next Step

Read Policies and Policy Sets to understand how grants become allow, deny, or step-up decisions.