Grants and scopes

# Grants and scopes

Canonical: https://docs.flowrelay.app/agent-access/grants-and-scopes/
Markdown: https://docs.flowrelay.app/agent-access/grants-and-scopes.md

Use the lowest useful grant, make expiry deliberate, and keep hard boundaries around billing, secrets, raw event data, and grant management.

## Operating rules
- Identify the job the agent is allowed to perform, such as setup inspection, event investigation, or recovery preparation.
- Choose the lowest authority tier and scopes that cover that job.
- Remember that authority controls what an agent may do; usage limits still control how much automated work can run in the plan period.
- Use a bounded expiry unless the merchant explicitly accepts the risk of longer access.
- Revoke the grant when the work is finished or when the partner no longer needs access.
- Review audit entries for sensitive reads, action previews, confirmations, replays, and diagnostics shares.

## Choose the lowest useful grant
Scope the grant to the task, endpoint, and time window the agent needs. Use expiry and revocation as normal controls, not exceptional cleanup. A grant that is narrow, expiring, and revocable is the safe default, not a degraded one.


## Authority tiers
Use these as customer-facing examples of grant shape. Exact scope identifiers belong in the Agent Operations API contract. Higher authority does not remove plan usage safeguards, and no tier grants broad Shopify, billing, or raw-secret access.


- Tier: Observer; Allows: Read docs, manifest, setup summaries, event history, receipts, and redacted diagnostics state; Does not allow: Replay, sharing diagnostics, endpoint edits, secret rotation, billing, or grant changes.
- Tier: Operator; Allows: Complete setup, create or edit endpoint setup, prepare endpoint tests, and submit structured support or expansion requests; Does not allow: Replay, diagnostics share creation, secret rotation, endpoint delete, billing, or grant changes.
- Tier: Recovery Operator; Allows: Use Operator access plus replay preview/execute, diagnostics preview/create, and secret rotation through approved action previews; Does not allow: Self-escalation, endpoint delete, broad Shopify authority, billing approval, grant changes, or raw secret access.
- Tier: Admin Assistant; Allows: Use Recovery Operator access plus permanent delete for archived endpoints, within the Agent Operations scopes the merchant explicitly grants for this store; Does not allow: Shopify billing approval, app install/uninstall, Shopify staff changes, grant self-escalation, Shopify Flow edits without separate authorization, or raw event-body/secret bypass.

## Audit
Sensitive reads, action previews, confirmations, replays, diagnostics shares, endpoint edits, and secret rotations leave audit context that preserves human or authorized-agent attribution.


## Usage is separate from authority
A grant may authorize an operation and still be refused when a usage meter or temporary safeguard is reached. Ask agents to inspect /agent/v1/plan-usage before high-volume work and to reduce unnecessary reads or previews when a meter is near its limit.


## Related
- [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation.md)
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits.md)
- [Action previews](https://docs.flowrelay.app/reference/action-intents.md)
- [CLI Reference](https://docs.flowrelay.app/reference/cli.md)

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.