Storefront API Generation of delegate access token Shopify-Storefront-Private-Token

Retired Boards Appdev Custom Storefronts

Topic summary

Developers are unable to properly generate and use delegate access tokens for the Shopify Storefront API’s Shopify-Storefront-Private-Token header, which is critical for server-side Hydrogen and headless storefronts to avoid rate limiting.

Core Issue:

  • Documentation instructs using delegate access tokens with the Shopify-Storefront-Private-Token header for server-to-server requests
  • The storefrontAccessTokenCreate mutation generates tokens, but they return 403 errors when used in the intended header
  • This blocks deployment of high-traffic Hydrogen sites

Resolution:
Shopify staff (_JCC) confirmed incremental rollout, initially limited to Hydrogen on Oxygen for Plus merchants. The feature is now live with updated documentation.

Working Solution:
Use the delegateAccessTokenCreate mutation (not storefrontAccessTokenCreate) with unauthenticated scopes like unauthenticated_read_product_listings, unauthenticated_write_checkouts, etc.

Important Notes:

  • The app generating the delegate token must already possess the requested scopes
  • Cannot execute the mutation via Shopify’s GraphiQL App; requires external tools (Postman/cURL) with proper admin API access token
  • Scope requirements differ from initial documentation examples
Summarized with AI on November 25. AI used: claude-sonnet-4-5-20250929.
6

Thanks for the find Sello_2k

That allows us to generate a token but sadly, not to use it.

In order to generate a token using this mutation, you must create a private app with both storefront API and admin API scopes. This mutation can then be triggered.

This will yield what appears to be a valid storefront access token.

In my trials, I was able to make requests to the storefront API api/2022-07/graphql.json when using the generated token under the header X-Shopify-Storefront-Access-Token.
Unfortunately, if I switched to using this token in the intended header of Shopify-Storefront-Private-Token I receive a 403 error.

It should be noted the store this is being on trials on is not a Shopify+ store. But that isn’t currently mentioned as a restriction to the use of this token in the documentation.

So it seems we are still stuck.

2 Likes