Resource servers
Shop API and MCP resources, scopes, subject-type policies, and no trailing slash.
Two resource servers serve the shop, both in infra/terraform/auth0. The Auth0 proxy’s own company API
(auth0_resource_server.poppy) is a separate, third resource.
| Resource | Identifier | Terraform | Purpose |
|---|---|---|---|
| Shop API | https://api.tarnandtimber.com |
api.tf |
The API audience |
| MCP | https://mcp.tarnandtimber.com |
mcp.tf |
The MCP server at its own domain |
Both use RS256, the rfc9068_profile token dialect and a one-hour token lifetime, with offline access allowed so
refresh tokens can be issued. The Shop API has fourteen scopes, pinned to API_SCOPE_DESCRIPTIONS in
@retail-demo/api/contracts/scopes by a cross-language test; the MCP resource has the nine agent scopes. There is no
shop-domain MCP alias: an MCP client checks that the protected-resource metadata’s resource equals the URL it
connected to (RFC 9728), so the server is reached only at its canonical URL.
These concrete identifiers belong to the existing personal deployment. For your shop, configure shop_api_origin
and shop_mcp_origin with your own exact HTTPS origins and use those values consistently in clients and discovery.
See deployment customization.
Identifiers have no trailing slash
Both origins are validated to be https://<host> with no path and no trailing slash, and validation rejects HTTP,
paths and trailing slashes. Auth0 matches resource= exactly, and many clients normalize a bare origin by adding a
slash. Audiences are never normalized in code.
Subject-type policies
| Resource | User tokens | Client tokens |
|---|---|---|
| Shop API | Require a client grant | Require a client grant |
| MCP | Require a client grant, satisfied by the third-party default grant | Denied |
Scopes
| Scope | Description | Granted to |
|---|---|---|
catalog:read |
Browse products, collections and stock | Website, storefront, agents |
cart:read, cart:write |
View and change the cart | Website, storefront, agents |
checkout |
Place orders | Website, storefront, agents |
orders:read, orders:write |
Read own orders; cancel and request returns | Website, agents (storefront reads only) |
account:read, account:write |
Read profile and addresses; change addresses | Website, agents |
payment_methods:read |
List saved cards (summaries) | Website, agents |
payment_methods:write |
Add, edit and remove saved cards | Website only |
account:security |
Sign-in sessions, contact changes, deletion | Website only |
guest |
Act for anonymous storefront visitors | Storefront only |
ops:read |
Read all customers and orders | Backoffice only |
agent:forward |
Forward an agent’s call and its original proof to the Shop API (webshop and MCP agent forwarders only) | Web agent forwarder and MCP agent forwarder only |
The MCP resource exposes only the agent subset: catalog, cart, checkout, orders, account and read-only payment methods.
Code catalogue descriptions
These are the exact descriptions in API_SCOPE_DESCRIPTIONS and Terraform. The scope text covers both agent forwarders,
which holds the scope too:
| Scope | Description |
|---|---|
catalog:read |
Browse products, collections and stock |
cart:read |
View the cart |
cart:write |
Change the cart |
checkout |
Place orders |
orders:read |
Read own orders |
orders:write |
Cancel orders and request returns |
account:read |
Read profile and addresses |
account:write |
Change addresses |
payment_methods:read |
List saved cards (summaries) |
payment_methods:write |
Add, edit and remove saved cards (human only) |
account:security |
Sign-in sessions, contact changes, deletion (human only) |
guest |
Act for anonymous storefront visitors (storefront only) |
ops:read |
Read all customers and orders (backoffice only) |
agent:forward |
Forward an agent’s call and its original proof to the Shop API (webshop and MCP agent forwarders only) |