Manage access scopes

Access scopes control what your app can read and write. This guide covers where to declare scopes, whether to make them required or optional, and how to change them after your app is installed. For the full list of scopes, see the access scopes reference. For how your app gets the access token that carries these scopes, see About app authentication.

Anchor to Where you configure scopesWhere you configure scopes

Where you declare your app's scopes depends on how your app is set up:

However you declare them, your app can only use a scope once it's been approved on the store. If your app acts only on stores in your own organization, you approve that change yourself when you release the version, so there's no merchant consent step.

Anchor to Choose your scopesChoose your scopes

Most apps start with a small set of scopes. The most frequently used GraphQL Admin API scopes are read_products, read_orders, read_customers, read_inventory, read_draft_orders, read_discounts, read_content, and read_themes, each with a write_ counterpart.

To find the scope a specific call needs, look up the field or mutation in the GraphQL Admin API reference. For the full list of scopes, including unauthenticated and customer scopes, see the access scopes reference.

Three things to know before you declare scopes:

• A write scope includes read. write_products grants read_products, so declare the write scope on its own when your app needs both. Declaring the read scope as optional while the write scope is required fails to deploy. See Moving a scope between scopes and optional_scopes.
• Orders are limited to the last 60 days. read_orders and write_orders cover that window. To reach older orders, request read_all_orders and declare it alongside them.
• More scopes reach protected customer data than you'd expect. Customer scopes are the obvious case, but orders, draft orders, fulfillments, abandoned checkouts, and store comments all carry customer data too. You can declare any of them, but outside of dev stores the API redacts protected fields until your app meets the protected customer data requirements and is approved.

None of these choices are permanent. You can change which scopes you declare, and whether each one is required or optional, after your app is installed. See Modify declared scopes.

Anchor to Access scope configurationsAccess scope configurations

There are two ways you can configure your access scopes: scopes, which merchants grant when they install your app, and optional_scopes, which your app requests later and merchants can decline.

Anchor to [object Object]scopes

Required access scopes. Merchants must grant these when they install your app, so your app is guaranteed to have them after installation.

Define them in the scopes field of your app's TOML file:

Anchor to [object Object]optional_scopes

Scopes your app requests after installation. Merchants can grant or decline them, and can revoke ones they've granted. Use optional scopes to offer features to some stores without requiring the same data access from every install.

Define scopes that your app can request dynamically in the optional_scopes field of your app's TOML file:

Your app requests these scopes after installation completes, if it needs them.

Anchor to Modify declared scopesModify declared scopes

To add or remove access scopes for your app, update your app's configuration TOML file and deploy the changes.

1. Modify the scopes or optional_scopes fields in your app's TOML file to include the access scopes you want.

2. Deploy the changes by running the following Shopify CLI command:

   Terminal

   Copy

   $

   shopify app deploy

3. Optionally, subscribe to the app/scopes_update topic to receive webhooks when the granted scopes change.

If your app doesn't use Shopify CLI, the step you take instead depends on how it's set up. For an app created in the Dev Dashboard, release a new version with the scopes you want. For an app that implements the authorization code grant itself, send the merchant through the authorization URL again with the updated scope list. In every case, merchants are prompted to approve scopes you add.

Anchor to Modifying the ,[object Object], fieldModifying the scopes field

If you modify the scopes field, then the following happens:

• Merchants are prompted to approve the updated access scopes when they open your app. The app/scopes_update webhook fires when the merchant approves the changes.
• If the change reduces scopes, the merchant isn't prompted and your app loses access to those scopes automatically when the merchant opens the app. The app/scopes_update webhook fires when the merchant opens the app.

Anchor to Modifying the ,[object Object], fieldModifying the optional_scopes field

If you modify the optional_scopes field, then the following happens:

• Your app can start requesting the new access scopes.
• The granted scopes for your app installation don't change until your app requests the new scopes dynamically and the merchant grants access. The app/scopes_update webhook fires when the merchant approves the changes.

Anchor to Moving a scope between ,[object Object], and ,[object Object]Moving a scope between scopes and optional_scopes

You can change whether a scope is required or optional by moving its handle between the scopes and optional_scopes fields, then deploying the change.

If you move a scope from scopes to optional_scopes, then the following happens:

• Stores that already granted the scope while it was required keep it. The scope is retained as an approved optional scope, so the merchant isn't re-prompted and the scope isn't revoked when they open your app. You don't need to request the scope again for existing installations.
• New installations don't receive the scope until your app requests it dynamically, the same as any other optional scope.

A required scope can't implicitly grant an optional one. For example, write_products grants read_products, so if you declare read_products as optional while write_products is still required, then deploying fails with the following error:

To resolve this, remove the implicitly granted scope from optional_scopes. In this example, you'd remove read_products, because write_products already grants it. If you want read_products to genuinely be optional, then move or remove write_products instead.

Anchor to Query currently granted scopesQuery currently granted scopes

Use a GraphQL Admin API query to get the currently granted access scopes for your app installation.

Shopify's API libraries wrap this query in a helper method:

Anchor to Request new access scopes dynamicallyRequest new access scopes dynamically

Requesting a scope asks the merchant to grant or decline it. What the merchant sees depends on the mechanism: the App Bridge method opens a permission grant modal on top of your running app, while the request URL and the React Router method redirect the browser to the Shopify admin.

If you're not using one of Shopify's API libraries, request access scopes by directing the merchant to the request URL:

For example:

Shopify's API libraries wrap this in a helper method, so you don't build the URL yourself:

The App Bridge method is client-side and asynchronous, so it doesn't redirect the browser:

The React Router method handles the request server-side. If the scopes aren't already granted, it performs a full-page redirect to the request URL:

Anchor to Revoke granted scopes dynamicallyRevoke granted scopes dynamically

If your app no longer needs certain access scopes from a merchant's store, then we recommend revoking them. This helps avoid a potential data leak if the access token is ever compromised.

Revoke access scopes with a GraphQL Admin API mutation:

Both libraries expose a revoke helper that wraps this mutation:

Anchor to Troubleshoot scope problemsTroubleshoot scope problems

What a scope failure looks like depends on what's blocking the call:

Anchor to Next stepsNext steps

• Look up the full list of scopes and what each one grants in the access scopes reference.
• Learn how to use the scopes API in the App Bridge library or the React Router library.
• Review how to declare access scopes in your app's configuration file.
• Understand how access tokens carry the scopes a merchant granted.