Delegate OAuth access tokens to subsystems

Some app architectures are split across multiple subsystems, with each one running on its own servers.

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.

Create a delegate access token

To create a new delegate access token, make an authenticated request to the following endpoint:


Provide the following parameters in the body of the request:

  • delegate_access_scope: The list of scopes that will be delegated to the new access token (required).
  • expires_in: The amount of time, in seconds, after which the delegate access token is no longer valid (optional). The requirements for this parameter depend on whether the parent access token is set to expire:

    • If it is, then expires_in must be set to a time before the parent token expires.
    • If if isn't, then expires_in accepts any length of time.


There are a few limitations to take into account when creating a delegate access token:

  • An application can delegate only the same or fewer scopes than were granted to it when asking for permission. It's not possible to request extra scopes using this endpoint. 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 application is re-authorized with fewer access scopes, all delegate access tokens will also lose the access scopes that are no longer authorized.
  • A delegate access token cannot be used to create new delegate access tokens.
  • A delegate access token can be used to make requests to any API endpoints that do not require access scopes. This includes, for example, uninstalling the application from a store. Make sure that only trusted parties have access to a delegated access token.