Use delegate tokens
Delegate access tokens are an artifact for making requests from private or authenticated contexts, like a server.
If you create a custom storefront with the Headless channel, then Shopify creates public and private access tokens for you.
This guide familiarizes you with delegate access tokens and describes how to create a delegate access token using the GraphQL Admin API.
How delegate access tokens work
Anchor link to section titled "How delegate access tokens work"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.
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.
The following diagram illustrates the delegate access token flow based on the actions of you, your app, and Shopify:
The developer creates an app and authenticates it to the GraphQL 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.
When should I create a delegate access token?
Anchor link to section titled "When should I create a delegate access token?"An example scenario is for 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 expiresIn 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 is an offline access token, 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 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.
Requirements
Anchor link to section titled "Requirements"You're familiar with API authentication.
You've retrieved an access token for the Admin API.
You can make an authenticated request to the Admin API for a parent token, which you'll use to authenticate your request for delegate access token.
You've reviewed the delegate access token overview, including the limitations and considerations.
Step 1: Create a delegate access token
Anchor link to section titled "Step 1: Create a delegate access token"Request a token from the GraphQL Admin API.
The following example requests an access token with write_orders permissions. It also sets an expiresIn value.
Step 2 (Optional): Make server-side requests to the Storefront API
Anchor link to section titled "Step 2 (Optional): Make server-side requests to the Storefront API"To query the Storefront API with a delegate access token:
- Include the
Shopify-Storefront-Private-Tokenheader with the delegate access token.
In some cases, a request to the Storefront API isn't linked to buyer traffic, such as during a static site build, however when making server-side requests to the Storefront API as a result of buyer traffic, be sure to also:
- Include the
Shopify-Storefront-Buyer-IP(case-sensitive) header with the IP address of the buyer. This allows Shopify to accurately enforce IP-level bot and platform protection, to help your storefront manage traffic from a single user consuming a high level of capacity, such as a bot.
API descriptions
Anchor link to section titled "API descriptions"| GraphQL field | Required? | Description |
|---|---|---|
delegateAccessScope |
Yes | The list of scopes that will be delegated to the new access token. |
expiresIn |
No | The amount of time, in seconds, after which the delegate access token is no longer valid. The requirements for this parameter depend on whether the parent access token is set to expire:
expiresIn provided, the token expires at the same time as the token that's used to create the delegate. If an offline token generates the delegate, then the delegate token doesn't expire. Learn more about the differences between online and offline access tokens. |
- Learn about rate limiting in the Storefront API.