Saleor MCP Authentication

There are two ways to connect to Saleor MCP. Staff use user OAuth: they sign in with their own Saleor Cloud account. Agents that run on their own use an access key. The server tells them apart by the bearer token it receives and rejects requests without a valid token.

Comparison

	User OAuth	Access key
Use it for	Assistants a staff member uses directly	Agents and automations that run on their own
MCP URL	`/mcp?saleor_api_url=…`, copied from the Connect page	`/mcp`, copied from the setup shown with the key
Credential	An access token the client gets through OAuth	A key created in Settings → Access keys
Acts as	The signed-in staff user	The app, limited to the key’s own access
Can read	Areas you approved, within the three permission levels	Areas where the key has Read or higher
Can write	Areas set to Edit that you approved. High-impact actions only in areas set to Full.	Areas where the key has Edit. High-impact actions only in areas set to Full.
Lifetime	Access token: 1 hour. Refresh token: replaced on each use, expires after 30 days without use.	90 days. It can be edited or revoked at any time.

MCP clients never receive a Saleor token.

User OAuth

Use user OAuth when a person works with the assistant. Copy the setup from Saleor MCP → Connect, as described in the quickstart.

The MCP URL includes your environment’s GraphQL API URL in the saleor_api_url parameter. Your client finds everything else on its own:

Authorization code flow with PKCE (S256)
Dynamic client registration for public clients
OAuth discovery through the protected resource metadata

When the client connects, you sign in with your Saleor Cloud account and see a consent screen. It offers only access you already have: the areas your group policy allows, limited by the app’s permissions and your own Saleor permissions. You can lower any area before you approve.

OAuth Scopes

Besides mcp, each scope names an area and a level, using Saleor’s permission codes:

Scope	Level
`MANAGE_ORDERS`	Read
`MANAGE_ORDERS:write`	Edit
`MANAGE_ORDERS:high_impact`	Full

Each level includes the ones below it. Access keys use the same codes.

A client can ask for specific scopes when it connects. Scopes can only narrow your access, never widen it:

If the client asks for specific scopes, the consent screen offers those, without any you don’t have.
If the client asks for no scope, the consent screen offers all the access you have, and nothing more.

Either way, the permission levels decide what you have, and you can lower any area before you approve.

Revoking a Connection

To end a connection, log out from your client if it offers that, or send one of the connection’s tokens to POST /oauth/revoke. Revoking a token revokes the whole connection it belongs to.

To take access away from a group, lower it in the group policy. This takes effect on the next request.

Access Keys

Use an access key for agents and automations that run without a person signed in.

A staff user with MANAGE_APPS and MANAGE_STAFF opens Saleor MCP → Settings → Access keys and creates a key.
They name the key and give it access per area, using the same levels as the group policy. They can grant only areas that they and the app both hold. See Managing access keys.
The key is shown once, with the setup for Codex, Claude Code, and other clients. Copy the setup for your client and store the key securely.

Keys expire after 90 days. Changes to a key and revocation apply to its next request. A key doesn’t depend on the person who created it.

The setup has the right MCP URL and sends the key in an Authorization: Bearer <access key> header:

Client	Setup shown with the key
Codex	A `[mcp_servers.saleor]` entry for `~/.codex/config.toml`
Claude Code	A `claude mcp add` command to run on the machine where the agent runs
Other clients	A JSON `mcpServers` entry for any client that supports remote MCP servers over Streamable HTTP

Calling the Server Directly

The transport is stateless Streamable HTTP. Every request is a single POST answered with JSON. There is no session to start and no stream from the server.

Use the MCP URL from the setup shown with your access key in place of https://<your-mcp-url>/mcp:

curl -X POST 'https://<your-mcp-url>/mcp' \
  -H 'Authorization: Bearer <access key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Endpoints

All paths are relative to the Saleor MCP address in the MCP URL on the Connect page.

Endpoint	Purpose
`POST /mcp`	MCP over Streamable HTTP. Add `?saleor_api_url=…` for user OAuth.
`GET /.well-known/oauth-protected-resource/mcp`	Protected resource metadata for one environment (`?saleor_api_url=…`).
`GET /.well-known/oauth-authorization-server`	Authorization server metadata.
`POST /oauth/register`	Dynamic client registration for public clients. Rate limited.
`GET /oauth/authorize`	Starts sign-in with Saleor Cloud and consent. Rate limited.
`POST /oauth/token`	Exchanges an authorization code or refresh token for MCP tokens. Rate limited.
`POST /oauth/revoke`	Revokes a token and the whole connection it belongs to. Rate limited.
`GET /api/oauth/upgrade`	Opens the browser approval for a permission upgrade link.
`GET /health`	Health check.

See Errors for rate limits.