Operator vs storefront scopes
Choose the smallest permission set for the job, whether an agent is helping a buyer or operating your store.
Which scopes to request for operating a workspace vs representing a buyer — and the MERCHANT_API_SCOPES set.
Aly distinguishes two integration modes: operator and storefront. The mode determines which scope set you ask the user to grant. Same MCP endpoint, same tools — different defaults for what the bearer can actually call.
Operator mode
The agent operates a workspace on behalf of its owner — creating sites, editing products, fulfilling orders, managing customers. This is the mode Claude Desktop or Cursor typically uses against your own workspace.
Operator-mode scopes cover the full agent surface:
read:sites,write:sites,delete:sitesread:content,write:contentread:customers,write:customersread:orders,write:ordersread:media,write:mediaread:analyticsmanage:voice,manage:domainsmanage:api_keys,manage:workspace,manage:team
read:orders and write:orders. A catalog importer needs read:content and write:content.Storefront mode
The agent represents a buyer — searching, comparing, opening a checkout. It should not see customer rows, order history, analytics, or workspace internals.
Storefront-mode scopes are narrow:
read:sites— read public site metadata.read:content— read products, collections, public CMS blocks.read:media— read public media assets.
Buyer-side checkout (UCP) does not require any of these scopes — guest checkout is allowed. Scopes only matter when you want the agent to do more than guest checkout, e.g. read a published catalog efficiently.
The MERCHANT_API_SCOPES set
The codebase ships a MERCHANT_API_SCOPES constant — the canonical operator-mode subset that excludes delete:sites, manage:api_keys, manage:workspace, and manage:team. It's the right default for a typical merchant integration (run the store; don't modify ownership).
| Scope | In MERCHANT_API_SCOPES |
|---|---|
read:analytics | Yes |
read:content / write:content | Yes |
read:customers / write:customers | Yes |
read:orders / write:orders | Yes |
read:sites / write:sites | Yes |
read:media / write:media | Yes |
delete:sites | No |
manage:api_keys | No |
manage:workspace | No |
manage:team | No |
manage:voice / manage:domains | No |
How tools enforce scopes
Every tool declares its required scope set. The server checks the token's granted scopes against that requirement before invoking the underlying Convex function. A missing scope produces a JSON-RPC error with code: -32603 and an error.data.required_scope field telling you exactly which scope to request.
Read-only mode
For visibility-only agents, use READ_ONLY_API_KEY_SCOPES — every read:* scope in the system. The token can list and get but never mutate.
Was this page helpful?