Delegate access tokens
Delegate access tokens are the recommended way for custom apps to make requests from private or authenticated contexts, like a server.
If you create a custom storefront with the Headless channel, Shopify creates public and private access tokens for you.
With public access, your requests are throttled by the IP that the request is from. With authenticated access, your requests are throttled at the shop level and optionally by a forwarded IP. This is advantageous because your server needs a much larger capacity for making requests for many buyers. The app throttle scales with the Shopify platform and isn't fixed. Under high load, such as for flash sales, both the platform and the throttle scale to support more requests.
This guide familiarizes you with delegate access tokens.
What's a delegate access token?
Anchor link to section titled "What's a delegate access token?"A delegate access token is an OAuth access token with a subset of the total permissions of an app.
Delegate access tokens are based on a parent API access token. The parent access token is used to authenticate your request for a delegate access token.
The following diagram illustrates the delegate access token flow based on the actions of you, your app, and Shopify:
The Partner creates an app and authenticates it to the GraphQL Admin or REST Admin API.
The app requests an access token for the shop from the Admin API. This is the parent token.
Shopify authenticates the app and issues the access token.
The app uses the access token to request a delegate access token.
Shopify validates the request and returns a delegate access token.
The delegate access token is used to make requests to the Admin or Storefront API.
You need only one delegate access token for a shop, unless you need to rotate the tokens or change the access scopes that are available to the token.
When should I create a delegate access token?
Anchor link to section titled "When should I create a delegate access token?"The following are some example scenarios for when you would create a delegate access token:
Requests from private or authenticated contexts to the Storefront API. Examples are an Oxygen deployment, Hydrogen backend, or a request from another server.
Admin API requests when app architectures are split across multiple subsystems, with each one running on its own server. Delegate access tokens avoid sharing a single access token between all subsystems, and ensure that each subsystem has access to only the minimal scopes that it needs to function properly.
When do delegate access tokens expire?
Anchor link to section titled "When do delegate access tokens expire?"You can explicitly declare an expires_in value for the delegate access token.
If you don't specify an expiry, then the token expires at the same time as its parent. If the parent token has offline access, then it won't expire and neither will the delegate access token. Otherwise, you'll need to rotate the parent and delegate tokens.
Limitations and considerations
Anchor link to section titled "Limitations and considerations"The following limitations and considerations apply to delegate access tokens:
An app can delegate only the same or fewer scopes than were granted to it when asking for permission. You can't request extra scopes using the REST or GraphQL Admin APIs. If a new scope is required, then the app must first be re-authorized with the new access scope by a user of the store.
When an app is re-authorized with fewer access scopes, all delegate access tokens lose the access scopes that are no longer authorized.
A delegate access token can't be used to create new delegate access tokens.
A delegate access token can be used to make requests to any API objects or resources that don't require access scopes. This includes, for example, uninstalling the app from a store. Make sure that only trusted parties have access to a delegated access token.
- Create a delegate access token using the GraphQL or REST Admin APIs.