---
title: Scopes API
description: The Scopes API lets you manage your app's <a href='https://shopify.dev/docs/api/usage/access-scopes'>access scopes</a> at runtime. You can query which scopes are currently granted, request additional
api_name: app-home
source_url:
  html: https://shopify.dev/docs/api/app-home/apis/authentication-and-data/scopes-api
  md: https://shopify.dev/docs/api/app-home/apis/authentication-and-data/scopes-api.md
---

# Scopes API

The Scopes API lets you manage your app's [access scopes](https://shopify.dev/docs/api/usage/access-scopes) at runtime. You can query which scopes are currently granted, request additional optional scopes from the merchant (which opens a permission grant modal), and revoke optional scopes you no longer need.

**Tip:**

To learn more about declaring and requesting access scopes, as well as required vs. optional scopes, refer to [manage access scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes).

### Use cases

* **Scope management:** Query, request, and revoke optional access scopes dynamically within your embedded app.
* **Progressive permissions:** Request additional scopes only when a merchant needs specific features.
* **Scope verification:** Check which scopes are currently granted before making API calls that require them.
* **Merchant consent:** Trigger the merchant consent flow for optional scopes directly from your app UI.

### Methods

The `scopes` API is available on the `shopify` global. All methods are asynchronous and return a Promise.

* **query**

  **() => Promise\<ScopesDetail>**

  **required**

  Returns the current access scopes for this app on this shop, including which are granted, required, and optional.

* **request**

  **(scopes: string\[]) => Promise\<ScopesRequestResponse>**

  **required**

  Opens a permission grant modal asking the merchant to grant the specified scopes.

  The scopes must be [access scope](https://shopify.dev/docs/api/usage/access-scopes) handles (for example, `'read_products'` or `'write_orders'`) that are declared as optional in your app configuration.

  See the [permission grant modal](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes#request-access-scopes-using-the-app-bridge-api-for-embedded-apps) documentation for more details.

* **revoke**

  **(scopes: string\[]) => Promise\<ScopesRevokeResponse>**

  **required**

  Revokes the specified optional scopes from this app on this shop.

  The scopes must be [access scope](https://shopify.dev/docs/api/usage/access-scopes) handles (for example, `'read_products'` or `'write_orders'`) that are currently granted and declared as optional. Required scopes cannot be revoked.

### ScopesDetail

* granted

  The scopes currently granted to this app on this shop. This includes both required and optional scopes.

  ```ts
  string[]
  ```

* optional

  The scopes declared as optional in your app configuration. These may or may not be currently granted — check \`granted\` to see which are active.

  ```ts
  string[]
  ```

* required

  The scopes declared as required in your app configuration. These are always granted at install time and cannot be revoked by the app.

  ```ts
  string[]
  ```

### ScopesRequestResponse

* detail

  The updated scopes for this app on this shop after the merchant's response.

  ```ts
  ScopesDetail
  ```

* result

  The merchant's response: \`'granted-all'\` if they accepted all requested scopes, or \`'declined-all'\` if they declined.

  ```ts
  UserResult
  ```

### UserResult

The merchant's response to a scopes request: \`'granted-all'\` if they accepted all requested scopes, or \`'declined-all'\` if they declined.

```ts
'granted-all' | 'declined-all'
```

### ScopesRevokeResponse

* detail

  The updated scopes for this app on this shop after the revocation.

  ```ts
  ScopesDetail
  ```

Examples

### Examples

* ####

  ##### Description

  Query the current scopes for your app on this shop. The response includes which scopes are granted, which are required, and which are declared as optional in your app configuration.

  ##### js

  ```js
  const {granted, required, optional} = await shopify.scopes.query();

  console.log(granted); // => ['read_products', 'write_products', 'read_orders']
  console.log(required); // => ['read_products', 'write_products']
  console.log(optional); // => ['read_orders', 'write_orders']
  ```

* ####

  ##### Description

  Request the merchant to grant additional optional scopes. This opens a permission grant modal where the merchant can accept or decline. The scopes you request must be declared as optional in your app configuration, and each value must be a valid access scope handle such as 'read\\\_products' or 'write\\\_orders'.

  ##### js

  ```js
  const response = await shopify.scopes.request([
    'read_products',
    'write_discounts',
  ]);

  if (response.result === 'granted-all') {
    console.log('Merchant granted access');
  } else if (response.result === 'declined-all') {
    console.log('Merchant declined access');
  }

  console.log(response.detail.granted);
  ```

* ####

  ##### Description

  Revoke optional scopes that your app no longer needs. The response includes the updated list of granted scopes. Only optional scopes can be revoked — required scopes cannot be removed.

  ##### js

  ```js
  const response = await shopify.scopes.revoke(['read_products']);

  console.log(response.detail.granted);
  ```

***

## Related

[Reference - Managing Access Scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes)

[API - Remix Scopes API](https://shopify.dev/docs/api/shopify-app-remix/v3/apis/scopes)

***