# Agent Access

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

Built from the ground up for agent operations, FlowRelay gives authorized agents receipts, scoped grants, action previews, redaction, and audit instead of raw event bodies and guesswork.

## What counts as an agent
An agent is a merchant-authorized software operator using a trusted private client or automation environment. Today that usually means Codex, Claude Code, the FlowRelay CLI run by a coding or ops agent, direct Agent Operations API calls from customer-controlled automation, or MCP Agent Operations access where enabled. FlowRelay is not hosting a separate chatbot for the merchant.


## Practical handoff
The normal handoff is the Agent Operations base URL plus a scoped grant token from the Agent Access screen. Give those values to the agent only through private secret, environment variable, CLI, or MCP host configuration. Do not put tokens in public examples, shared prompts, docs, tickets, screenshots, or repo files.


## What Agent Access is for
Agent Access lets a merchant authorize a trusted agent to inspect setup, receipts, recovery options, diagnostics, and approved action previews through scoped FlowRelay operations.


## Usage limits still apply
Agent Access is included with published monthly protective limits. Authority tiers decide what an agent may do; the plan's Agent Operations limits decide how much automated read, preview, and execution work can run in the period.


## What stays human-controlled
Billing approval, grant changes, Shopify Flow workflow edits, support submission, raw event data access, and authority expansion stay under human control unless separately authorized. Agents may receive one-time endpoint setup secrets only when the scoped operation explicitly returns them, such as endpoint creation or secret rotation.


## Agent jobs
Choose authority based on the job, not the agent's convenience.


- Job: Explain what happened to an event; Typical access: Read setup, event history, receipts, and safe diagnostics context.
- Job: Prepare recovery; Typical access: Preview replay or diagnostics actions without executing outside the grant.
- Job: Execute a recovery action; Typical access: Execute only the approved action with idempotency and audit.

## Operating rules
Use these controls to keep agent access scoped and reversible.
1. Open Agent Access from FlowRelay inside the merchant-authorized Shopify app context.
2. Review the plan's published Agent Operations limits before authorizing high-volume agent work.
3. Treat an agent as a merchant-authorized software operator in a trusted private client, not a FlowRelay-hosted bot or a separate Shopify user.
4. Choose the lowest useful authority tier and scope for the work the agent is allowed to perform.
5. Set an expiry that matches the task, then create or review the grant from the human admin surface.
6. Give the agent https://api.flowrelay.app plus the scoped grant token through private secret, environment, CLI, or MCP configuration.
7. Have the agent start from the docs index, Markdown pages, /agent/v1/manifest, and the FlowRelay Operator Skill before using API, CLI, or MCP Agent Operations access.
8. Use mission playbooks and availability guidance so the agent can map the operator's goal to safe context gathering, allowed actions, and refusal handling.
9. Keep billing approval, grant changes, Shopify Flow edits, secrets, raw event data, and support requests under explicit human control unless separately authorized.

## Related
- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes.md)
- [Agent mission playbooks](https://docs.flowrelay.app/agent-access/agent-mission-playbooks.md)
- [Availability and refusals](https://docs.flowrelay.app/agent-access/availability-and-refusals.md)
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits.md)
- [API Reference](https://docs.flowrelay.app/reference/api.md)
- [MCP Reference](https://docs.flowrelay.app/reference/mcp.md)

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