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.
10

Thanks for your question about this. We’re rolling this out incrementally. The first priority was for Hydrogen, and is also why you’re able to find general details in our docs. Once we’re at 100% rollout we’ll update the developer changelog, and provide additional documentation on how to proper utilize the request headers you’ve identified.

I don’t have an exact timeline to share today, and while things can change, I feel fairly confident that you’ll see this be fully available later this quarter.

1 Like