Agent Access

Set up with an agent

Use this guide when an operator wants an authorized agent to help set up a new external-event lane without handing the agent broad store authority.

Reference Read Endpoint swap plan.

Agent workflow

Agents should orient through docs before using authenticated tools.

Confirm the current edition is FlowRelay for Shopify Flow and the operator has authorized this store, grant, and task.
Run docs, whoami or grant, setup-state, and plan-usage before creating or changing anything.
Identify the sender, event purpose, supported trigger variant, payload fields, authentication method, expected monthly volume, and criticality.
Create or inspect one endpoint only when the grant includes endpoint write authority and the operator confirms the trigger choice.
Hand Shopify Flow trigger setup and sender URL/auth setup to the operator or separately authorized owner; FlowRelay does not edit Shopify Flow or the sender.
Send one test event with synthetic data, then confirm FlowRelay accepted it and handed it to Shopify Flow.
Ask the operator to confirm any downstream Shopify Flow result separately. Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.
Recommend monitoring cadence from traffic, criticality, and recent failures, then produce a short operator summary.

Approval checkpoints

Agents operate only through scoped, revocable grants and explicit operator approval; they are governed operators, not privileged bypasses. They are bound by refusal reasons, action previews, idempotency, usage metering, redacted summaries, and audit. They must not ask for Shopify tokens, session data, database URLs, raw event bodies, full authentication headers, endpoint secrets, HMAC values, customer data, copied logs, browser storage, cookies, or broader Shopify authority through FlowRelay.
Stop for operator approval before choosing an unclear trigger variant, creating an endpoint, changing sender URL/auth, enabling production traffic, replaying an event, submitting support, requesting more capacity, or treating another platform edition as live.
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.

Use this for #

Use this setup guide when the merchant is creating a new external-event lane. For an existing endpoint, receiver, webhook app, serverless function, or agency-built path, use the endpoint swap plan instead.

Grant needed #

Use a store-scoped, time-bounded Agent Access grant for the exact setup job. Operator is the default when the agent will create or edit endpoint setup, prepare endpoint tests, and prove one safe event. Use Observer when the agent only reviews setup, receipts, events, plan usage, or diagnostics state. Use Recovery Operator only when the task includes replay, diagnostics share creation, or secret rotation. Do not use Admin Assistant for normal setup guides; reserve it for exceptional broader store operations.

Grants and scopesCompare Observer, Operator, Recovery Operator, and Admin Assistant.

Copyable agent instructions #

Paste this into an authorized agent session after the merchant has created a scoped Agent Access grant. Replace bracketed details, keep tokens in environment variables or the agent client's secret store, and do not include secrets, raw payloads, or customer records. Stop and get operator approval before: the Shopify Flow trigger, the endpoint, the sender URL/auth, any production traffic, replay, support submission, or requesting more capacity.

Agent setup brief Use for one new FlowRelay endpoint and one safe proof event.

You are helping set up FlowRelay for Shopify Flow for [store/domain].

Goal: create or prepare one new FlowRelay endpoint, prove one test event with synthetic data, and produce an operator-readable summary. Work only inside the store-scoped, time-bounded FlowRelay Agent Access grant for this task. Use Operator authority only when endpoint setup changes are authorized. Use Observer for read-only review. Use Recovery Operator only if replay, diagnostics share creation, or secret rotation is explicitly in scope. Do not ask for endpoint secrets, authentication headers, HMAC values, Shopify tokens, session data, raw event bodies, customer records, database URLs, store passwords, copied private logs, or screenshots containing private values.

Token handling:
- Receive the scoped Agent Access token only through private secret, environment variable, CLI profile, or MCP host secret configuration.
- Never paste the token into prompts, docs, tickets, screenshots, logs, repo files, or shared notes.

Before changing anything:
1. Read https://docs.flowrelay.app/llms.txt and https://docs.flowrelay.app/agent-access/setup-with-an-agent/.
2. Read the Agent Operations manifest at https://api.flowrelay.app/agent/v1/manifest.
3. Confirm the grant/store identity with whoami or GET /agent/v1/grant.
4. Read setup-state and plan-usage.

Inventory:
- sender/source system and owner
- event purpose and Shopify Flow trigger variant
- expected monthly event volume and criticality
- authentication mode the sender can support
- testing owner and rollback owner
- whether Shopify Flow trigger setup is separately authorized

Rules:
- Create or edit one endpoint only if the grant allows it and the operator approves the trigger choice.
- Stop for operator approval before sender URL/auth changes, Shopify Flow workflow changes, billing/capacity changes, grant changes, replay, diagnostics sharing, or production traffic.
- Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.
- If FlowRelay returns 429, obey Retry-After, retryAfterSeconds, resetAt, rateLimitClass, scope, and recommendedAction.

Final output:
Give the operator a concise summary with the sender/workflow, endpoint and trigger choice, test result, plan fit, recommended monitoring cadence, risks, unresolved approvals, rollback owner, and next safe action.

Setup inventory #

Before endpoint creation, the agent should collect only setup facts: sender owner, current platform or source type, event purpose, trigger variant, required JSON paths, authentication method, expected volume, criticality, testing owner, rollback owner, and whether Shopify Flow setup is separately authorized. Do not ask for endpoint secrets, auth headers, tokens, raw payloads, customer data, or copied private logs.

When FlowRelay refuses #

A refusal is part of the product contract. The agent should preserve the refusal reason, docs URL, retry or usage guidance, required scope, and suggested next action instead of trying another surface. Missing scope, expired retention, no_workflow, rate limits, billing handoff, unsafe replay, and human-only grant changes each require the specific next safe action the response names.

Proof checklist #

Confirm the test event with synthetic data was accepted and handed to Shopify Flow. Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed. Confirm downstream results separately.

Monitoring cadence #

During setup or cutover, monitor more closely until the first delivered proof is clean. After that, low-risk or low-volume lanes can use light periodic checks, while high-volume, revenue-impacting, or recently failing lanes should check more frequently and read plan-usage before broad reads or polling. Any 429 response means obey Retry-After, narrow the target set, and stop tight loops.

Operator summary #

End with a short summary the operator can scan: sender and workflow, endpoint and trigger choice, test result, plan fit, recommended monitoring cadence, risks, next approvals, and any external owner who still needs to act.

START

USE CASES

SET UP

OPERATE

RECOVER

AGENT ACCESS

REFERENCE