Delegate OAuth access tokens to subsystems
A delegate access token is an access token with a subset of the total permissions of an app. This guide describes how to create a delegate access token and the limitations and considerations associated with delegate access tokens.
Create a delegate access token by making an authenticated request to the REST Admin API or GraphQL Admin API.
When to create delegate access tokensAnchor link to section titled "When to create delegate access tokens"
The following are scenarios where you would create delegate access tokens:
Multiple subsystemsAnchor link to section titled "Multiple subsystems"
Some app architectures are split across multiple subsystems, with each one running on its own server.
In these cases, it's best to avoid sharing a single access token between all the subsystems, and make sure each subsystem has access to only the minimal scopes it needs to function properly. You can do this by creating delegate access tokens that are based on a parent access token. This approach can improve your app's security and make it easier to rotate your access tokens.
Authenticated Storefront API accessAnchor link to section titled "Authenticated Storefront API access"
Authenticated access to the Storefront API enables your app to make requests from private or authenticated contexts like an Oxygen deployment, Hydrogen backend, or other server. Learn more about Storefront API authentication.
How to create a delegate access tokenAnchor link to section titled "How to create a delegate access token"
To create a new delegate access token, make an authenticated request to the REST Admin or GraphQL Admin:
API descriptionsAnchor link to section titled "API descriptions"
|REST property||GraphQL field||Required?||Description|
||Yes||The list of scopes that will be delegated to the new access token.|
||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:
Limitations and considerationsAnchor 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.