# Set the authorization ceiling

Declare the most authority an agent's own tokens can ever carry, in the three scope grammars the platform accepts, and understand what the ceiling does and does not govern.

`policy.scope_ceiling` is the upper bound on what an agent may do acting as itself. Anything that
mints authority for the agent intersects the request with this ceiling; nothing widens it.

```yaml title="agent.yaml"
policy:
  scope_ceiling:
    - "llm:your-model-family:invoke"
    - "mcp:github:create_issue:write"
    - "calendar.read"
  allowed_audiences:
    - "https://your-workspace-api.example"
```

- Three grammars, no wildcards: `<resource>.<action>`, `mcp:<server>:<tool>:<verb>`,
  `llm:<model>:<capability>`.
- Required on a hosted control plane. Where it is optional, an absent ceiling means allow-all with
  a warning.
- It governs **delegation** between agents and any future scoped token exchange. It does not
  govern the model allowlist or connector tool allowlists; those have their own controls.
- Changing it is a new version. The broker reads the registered contract with a short cache, on a
  separate clock from traffic rollout.

## Write the entries

| Form | Example | Covers |
|---|---|---|
| `<resource>.<action>` | `calendar.read` | A capability on a named resource |
| `mcp:<server>:<tool>:<verb>` | `mcp:github:create_issue:write` | One tool on one connector, with a verb |
| `llm:<model>:<capability>` | `llm:your-model-family:invoke` | Calling a model family |

Every entry must match exactly one grammar. Wildcards are rejected at validation, so you cannot
write `mcp:github:*`. Keep the list to what the agent actually does: a ceiling is the maximum,
and every entry is authority the agent could be granted.

When you change `model`, update the matching `llm:<family>:invoke` entry, or the declared ceiling
stops describing the model the agent calls.

## What the ceiling governs

- **Agent-to-agent delegation.** On a delegated call the caller's ceiling is intersected with the
  callee's, and only scopes inside both are granted. An agent with no ceiling cannot receive a
  delegated grant at all.
- **Token exchange.** If a supported flow exchanges a token against one of the agent's
  `allowed_audiences`, a requested scope outside the ceiling is refused. No public runtime
  workflow exposes that exchange today; the contract is held.

## What it does not govern

| Concern | Where it is actually enforced |
|---|---|
| Which model a run may call | `permitted_models`, at the LLM gateway |
| Which integration tools an agent may use | `integrations.<key>.tools.allow`, at the connector gateway |
| Which actions pause for a person | `policy.approval_required_tools` and connector `approval_required_tools` |
| Which external hosts the agent may reach | `network.egress` and the tenant ceiling, at the egress proxy |

Adding an `mcp:...` scope does not approve a connector tool, and adding an `llm:...` scope does
not replace the model allowlist. Sizing the ceiling for those will not work.

## Change it safely

The ceiling is part of the version's contract, so changing it means a new version. Two clocks
apply: traffic follows enablement, while the authorization contract is read from the agent's
registered manifest through a short in-process cache. A registration can change the contract
before the new version serves traffic, and rolling traffic back does not necessarily restore the
earlier contract. Review authorization impact at registration time and verify the effective
contract after a change.

## Where to go next

- [Identity and access](/concepts/identity-and-access): the identity modes and why authority
  only narrows.
- [Delegate work to another agent](/guides/run/delegate-to-another-agent): the ceiling in use.
- [Agent manifest](/reference/agent-manifest#authorization-contract): the field reference.