Agent Access

# Agent Access

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

Agent Access lets you authorize a trusted agent through scoped, expiring, audited grants. The agent can inspect FlowRelay setup, receipts, recovery options, and diagnostics, then prepare or run approved actions. Agent Access is designed so an agent does not need raw payloads, secrets, or broad store authority to help. Billing, grant changes, Shopify Flow edits, and your secrets stay under human control unless you separately authorize them.

## What Agent Access is for
Agent Access lets you authorize a trusted agent to inspect setup, receipts, recovery options, and diagnostics, and to prepare approved action previews — all through scoped FlowRelay operations. Authority is chosen per job and expires with the task.


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


## How to set up a grant safely
- Open Agent Access from FlowRelay inside the merchant-authorized Shopify app context.
- Review usage limits, short-window rate limits, and fair-use guidance before authorizing high-volume agent work.
- Treat an agent as a merchant-authorized software operator in a trusted private client, not a FlowRelay-hosted bot or a separate Shopify user.
- Choose the lowest useful authority tier and scope for the work the agent is allowed to perform.
- Set an expiry that matches the task, then create or review the grant from the human admin surface.
- Give the agent https://api.flowrelay.app plus the scoped grant token through private secret, environment, CLI, or MCP configuration.
- 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.
- Use mission playbooks and availability guidance so the agent can map the operator's goal to safe context gathering, allowed actions, and refusal handling.
- Keep billing approval, grant changes, Shopify Flow edits, secrets, raw event data, support requests, and product-demand requests under explicit human control unless separately authorized.

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


## Usage limits still apply
Agent Access is included with governed usage safeguards. Authority tiers decide what an agent may do; exact Agent Operations meters and short-window rate limits decide how much automated read, preview, and execution work can run safely in the period.


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

## 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 share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.