Shopify Authentication

generated: '2026-08-27'
method: searched
source: >-
  https://shopify.dev/docs/apps/build/authentication-authorization,
  https://shopify.dev/docs/api/usage/access-scopes.md (HTTP 200),
  https://shopify.dev/docs/api/usage/response-codes.md (HTTP 200),
  https://api.shopify.com/.well-known/oauth-authorization-server (HTTP 200),
  https://catalog.shopify.com/.well-known/oauth-protected-resource (HTTP 200),
  https://shopify.dev/docs/apps/build/storefront-mcp/servers/customer-account.md (HTTP 200)
  — all fetched 2026-08-27. Supersedes the 2026-07-11 derived profile, which read only the
  Admin REST OpenAPI and therefore saw one apiKey scheme where five distinct schemes exist.
docs: https://shopify.dev/docs/apps/build/authentication-authorization
provider: Shopify
providerId: shopify
summary:
  types:
  - apiKey
  - oauth2
  - openIdConnect
  api_key_in:
  - header
  versioned: false
  versioning_note: >-
    The OAuth endpoints — including AccessScope — are explicitly listed as UNVERSIONED. They can
    change at any time, with no deprecation window, while every API they authorize is versioned
    quarterly.
schemes:
- name: AccessToken
  type: apiKey
  in: header
  parameter: X-Shopify-Access-Token
  api: Admin REST API, GraphQL Admin API
  description: Access token obtained via the OAuth authorization code grant or token exchange.
  sources:
  - openapi/_original/shopify-admin-rest-api-openapi.yml
  - https://shopify.dev/docs/apps/build/authentication-authorization
- name: StorefrontAccessToken
  type: apiKey
  in: header
  parameter: X-Shopify-Storefront-Access-Token
  api: Storefront API
  description: >-
    Public or private storefront access token. Server-side requests with a private token must also
    send the correct Buyer IP header or risk a 430 Shopify Security Rejection.
  sources:
  - https://shopify.dev/docs/api/storefront
- name: CustomerAccountOAuth
  type: oauth2
  flow: authorization_code with PKCE
  api: Customer Account API, Customer Accounts MCP
  discovery: https://{shop-domain}/.well-known/openid-configuration
  description: >-
    Per-customer authorization. A 401 from the Customer Accounts MCP server is the documented signal
    to start the flow. Requires a custom domain on the store and Level 2 protected customer data
    approval from the Partner Dashboard.
  sources:
  - https://shopify.dev/docs/apps/build/storefront-mcp/servers/customer-account
- name: AgentClientCredentials
  type: oauth2
  flows: [client_credentials, 'urn:shopify:params:oauth:grant-type:ecp-credentials', 'urn:ietf:params:oauth:grant-type:jwt-bearer']
  issuer: https://api.shopify.com
  token_url: https://api.shopify.com/auth/access_token
  token_endpoint_auth_methods: [client_secret_post]
  api: UCP Catalog / Cart / Checkout MCP
  description: >-
    Agent authorization for the UCP surfaces. Buys the token tier — the highest rate limits, and the
    only tier that can call complete_checkout. Metadata is served per RFC 8414 at
    https://api.shopify.com/.well-known/oauth-authorization-server, with the protected resource
    declared per RFC 9728 at https://catalog.shopify.com/.well-known/oauth-protected-resource.
  sources:
  - well-known/shopify-api-oauth-authorization-server.json
  - well-known/shopify-catalog-oauth-protected-resource.json
  - https://shopify.dev/docs/agents/carts-and-checkout/checkout-mcp
- name: None (anonymous)
  type: none
  api: Global Catalog MCP, Storefront MCP, mock.shop
  description: >-
    Genuinely anonymous surfaces. https://catalog.shopify.com/api/ucp/mcp answered a tools/list with
    no credential at all (HTTP 200, verified 2026-08-27), the per-store Storefront MCP endpoints are
    documented as requiring no authentication, and https://mock.shop/api answers full GraphQL
    introspection unauthenticated. Anonymous callers get the lowest rate-limit tier and cannot reach
    Checkout MCP.
  sources:
  - mcp/shopify-catalog-mcp-tools.json
  - https://shopify.dev/docs/apps/build/storefront-mcp/servers/storefront
token_lifetimes:
  note: >-
    Non-expiring offline access tokens are being retired. From 2027-01-01 an Admin API request
    presenting a public app's non-expiring offline access token returns 403 with the message
    "Non-expiring access tokens are no longer accepted for the Admin API".
  docs: https://shopify.dev/docs/apps/build/authentication-authorization/migrate-to-expiring-offline-access-tokens
failure_signals:
  '401': Missing, incorrect or expired credentials. A 401 carrying invalid_request with "This request requires an active refresh_token" is FINAL — do not retry.
  '403': Missing scope. From 2027-01-01, also a non-expiring offline token on the Admin API.
  '430': Shopify Security Rejection — often a server-side Storefront request without the Buyer IP header.
scopes:
  cross_reference: scopes/shopify-scopes.yml
  count: 137
  families: [authenticated, unauthenticated, customer]