Scope Grants: Fine-Grained Access Control for AI Agents
Scope grants are the permission model of the Never-Leak Protocol. They define exactly what an agent can do with a specific secret, with built-in expiration, usage limits, and conditions.
What is a Scope Grant?
A scope grant is a permission object that defines exactly what an agent can do with a specific secret. Unlike traditional role-based access control (RBAC) where a role grants broad access to many resources, scope grants are deliberately narrow: one agent, one secret, one set of allowed actions, with explicit conditions.
Think of it this way: RBAC says "this user is an admin, so they can do anything." A scope grant says "this agent can use this specific secret for these specific action types, only until this date, and only this many times."
Anatomy of a Scope Grant
Every scope grant is a structured JSON object that specifies the secret, the allowed actions, and the conditions under which the grant is valid.
{
"secret": "production/db-password",
"actions": ["exec", "template"],
"conditions": {
"valid_from": "2026-01-01T00:00:00Z",
"valid_until": "2026-03-01T00:00:00Z",
"max_uses": 100,
"ip_whitelist": ["10.0.0.0/8"]
}
}
Let's break this down. The secret field identifies which secret this grant applies to, using a path-based naming convention. The actions array lists the specific action types the agent is allowed to perform. And the conditions object sets the boundaries.
Key Properties
Every grant has a valid_from and valid_until timestamp. Grants expire automatically -- there is no such thing as a permanent scope grant. If an agent needs continued access, a new grant must be issued.
The max_uses field caps how many times the secret can be accessed under this grant. This prevents an agent from making an unbounded number of requests, even within the time window. Once the limit is reached, the grant is exhausted.
Grants can include additional conditions like IP whitelists, environment constraints (e.g., only in staging), or required metadata fields. These conditions are evaluated at request time, and any failure means the request is denied.
The actions array restricts which types of operations the agent can perform. A grant allowing exec does not automatically allow read. Action types include exec (execute a command), template (populate a template), and read (read the value directly, if permitted).
The Subset Rule
One of the most important security properties of scope grants is the subset rule: when one agent delegates access to another agent, the delegated scope can only be equal to or narrower than the original.
This means no agent can escalate its own privileges or grant more access than it has. If Agent A has a scope grant allowing 100 uses until March 1st, it can delegate to Agent B with 50 uses until February 15th, but it cannot delegate 200 uses or extend the expiration.
// Agent A's scope grant { "secret": "prod/api-key", "actions": ["exec", "template"], "max_uses": 100 } // Agent A delegates to Agent B (valid - narrower scope) { "secret": "prod/api-key", "actions": ["exec"], "max_uses": 50 } // Agent A tries to delegate more (REJECTED - violates subset rule) { "secret": "prod/api-key", "actions": ["exec", "read"], "max_uses": 200 }
How It Compares
Scope grants take the best ideas from existing access control models and adapt them for the unique challenges of AI agent security.
| Property | Traditional RBAC | OAuth Scopes | NL Scope Grants |
|---|---|---|---|
| Granularity | Role-level | API-level | Per-secret, per-action |
| Expiration | Manual removal | Token expiry | Built-in, mandatory |
| Usage limits | None | Rate limits | Per-grant max uses |
| Delegation | Not supported | Limited | Subset rule enforced |
| Secret visibility | Full access | Full access | Opaque handles only |