---
title: Clients and grants
description: Website, storefront, backoffice, agent forwarder and MCP clients, with third-party defaults.
sidebar:
  order: 3
---

Every caller has its own Auth0 client and an explicit grant. Nothing is inherited. Machine clients allow only client
credentials and use `client_secret_post`.

| Client                                      | Type                                  | Grant on the Shop API                                              | Scopes                                                                        |
| ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Website                                     | Regular web app                       | User                                                               | Agent scopes plus `payment_methods:write` and `account:security`              |
| Storefront                                  | Machine to machine                    | Client                                                             | `catalog:read`, `cart:read`, `cart:write`, `checkout`, `orders:read`, `guest` |
| Backoffice (`backoffice_api`)               | Machine to machine                    | Client                                                             | `ops:read` only                                                               |
| MCP server (`shop_mcp`)                     | Custom API client (`resource_server`) | User, through On-Behalf-Of                                         | Agent scopes only                                                             |
| Proxy Auth0                                 | Regular web app                       | User, through CTE                                                  | Agent scopes only, on the Shop API and the MCP resource                       |
| Independent agent (`personal_agents`)       | Confidential regular web app          | No direct Shop API grant; invited-agent CTE and Session Delegation | Approved owner-backed browser permissions only                                |
| Web agent forwarder (`web_agent_forwarder`) | Machine to machine                    | Client                                                             | Agent scopes plus `agent:forward`                                             |
| MCP agent forwarder (`mcp_agent_forwarder`) | Machine to machine                    | Client                                                             | `catalog:read`, `cart:read`, `cart:write`, `agent:forward`                    |

The storefront grant excludes all `account:*`, `payment_methods:*` and `ops:*` scopes. The backoffice grant is
exactly `ops:read`. Neither agent forwarder can acquire guest, operator, card-write or account-security authority, and the API
accepts an agent-forwarder token only together with exactly one original artifact (see
[Callers and tokens](/architecture/callers-and-tokens#poppy-and-forwarded-agent-admission)). Agent forwarder and storefront credentials are
secret stack bindings and never appear in plain settings.

## Independent invited agents

The optional `personal_agents` client authenticates independent identities in the `agents` connection. It uses a
separate invited-agent exchange profile and Session Delegation into the website; shared commerce calls subsequently
use the web agent forwarder with live consent checks. Its own rotating refresh token belongs to its independent login, while
the delegated website session has no delegated refresh token. It is not a Poppy Account Token or a direct API grant.
See [invited-agent setup](/architecture/auth0/invited-agents) for the required switches, platform registrations and bindings.

## Self-registered MCP clients

MCP clients register themselves through Dynamic Client Registration. They are third-party clients in strict mode. A
**default grant for third-party clients** gives them the agent scopes on the MCP resource and nothing else.

- The default grant covers every third-party client in the tenant, including ones created later. That is acceptable
  because it only covers the MCP resource, never the Shop API.
- A dynamic client can't get a Shop API token directly. Auth0 refuses, because no third-party grant exists for that
  audience.
- An MCP token presented directly to the API is rejected on audience.

## The MCP server's own identity

The MCP server has one Custom API client linked to the MCP resource, allowed to perform only the On-Behalf-Of
exchange. It authenticates with a client secret held in the MCP Worker's secrets (`MCP_CLIENT_ID`,
`MCP_CLIENT_SECRET`). Its grant to the Shop API is user-delegated and limited to agent scopes, so even with route
guards disabled Auth0 would refuse to issue `payment_methods:write`, `account:security`, `guest` or `ops:read` to it.

## Management clients

- **`shop_management`** is bound to the webshop Worker. It requests exactly `read:sessions`, `delete:sessions` and
  `delete:refresh_tokens` for browser session listing and revocation. Selected browser actions and sign out everywhere
  deny linked Poppy grants through the Auth0 proxy before requesting Auth0 revocation with refresh tokens.
- **`ops_management`** serves the API's operator customer reads through `API_OPS_MANAGEMENT_*`; its grant is exactly
  `read:users`. Terraform `moved` blocks (`contract-moves.tf`) keep the identity it had as `backoffice_management`.

The website client's back-channel logout URL points at the webshop (`website_backchannel_logout_url`,
`https://<shop>/api/auth0/backchannel-logout`), not at the API. See
[back-channel logout](/architecture/request-flows/back-channel-logout).

## Refresh tokens for the website

The website's refresh-token policy covers the Shop API with `website_api_scopes` and, when enabled, My Account with
`shop_my_account_scopes`, so one refresh token serves both (multi-resource refresh tokens). Every website login
requests the Shop API audience, and rotation keeps zero leeway. See [My Account](/architecture/auth0/my-account).