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

Hey @DrewGarratt thanks for the feedback, and correct right now it’s just a promise of something on it’s way.

The Hydrogen sales channel that sets up Oxygen for a Hydrogen based custom storefront is only available for plus merchants right now. At some point in the future you’ll also see the Hydrogen channel made available to standard and advanced plans. If you’re having any problems with the Hydrogen channel on a plus store today please let me know.

Finally, I just wanted to correct something. The new headers Shopify-Storefront-Private-Token and Shopify-Storefront-Buyer-IP are intended to be used for server to server requests in the context of the Storefront API. When this is all released the value provided to Shopify-Storefront-Private-Token will be a token created with delegateAccessTokenCreate.

1 Like