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 data, and grant management.

## 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.


## Authority tiers
Use these as customer-facing examples of grant shape. Exact scope identifiers belong in the Agent Operations API contract.


- 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: Recovery preparer; Allows: Preview replay or diagnostics intents and explain the required human decision.; Does not allow: Execute side-effecting recovery without an execution grant.
- Tier: Recovery operator; Allows: Execute specific governed recovery actions that were previewed and are inside the grant.; Does not allow: Self-escalation, broad Shopify authority, support submission, billing approval, or raw secret access.

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


## Operating rules
Use these controls to keep agent access scoped and reversible.
1. Identify the job the agent is allowed to perform, such as setup inspection, event investigation, or recovery preparation.
2. Choose the lowest authority tier and scopes that cover that job.
3. Use a bounded expiry unless the merchant explicitly accepts the risk of longer access.
4. Revoke the grant when the work is finished or when the partner no longer needs access.
5. Review audit entries for sensitive reads, action-intent previews, confirmations, replays, and diagnostics shares.

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

## Safety Boundary
Do not include raw payloads, endpoint secrets, auth headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.