Permission scopes

Scopes translate the CQRS split into policy. They let you give an agent exactly the power it needs — and nothing more.

Read-only keys

A key can be read-only: it can run every query and no command. This is the default choice for anything that only needs to read — dashboards, reporting agents, search integrations. A read-only key cannot change data by construction, not just by convention.

This maps directly onto CQRS: read scopes cover queries; anything that changes state requires a write-enabled key. See CQRS.

Scoped to specific capabilities

Beyond the read/write split, access is scoped to specific capabilities. An agent that processes documents gets document endpoints; it does not get banking actions. For vendor integrations, capability gating works per integration type — each integration reaches exactly the endpoints granted to it.

Destructive actions gated separately

Deleting data is not the same as changing it. Destructive actions are gated separately from ordinary writes: a key that can create and update documents still cannot delete them unless explicitly granted. Combined with soft delete and the audit trail, this means an agent can do its job while the most damaging class of actions stays behind an extra gate.

Choosing scopes in practice

• Reporting agent → read-only.
• Support bot that logs notes → read + write, capability-scoped, no destructive actions.
• Migration tooling → the full scope it needs, run by a company-level agent — and disabled the moment the migration is done.

Scope decisions are visible in the log: what an agent could have done is part of understanding what it did. Read next: Rollback — or Change attribution for how the log works.