---
title: Scopes
description: >-
  The Scopes API provides the ability to dynamically manage your access scopes
  within an embedded context.

    > Tip:
    > To learn more about declaring and requesting access scopes, as well as required vs. optional scopes, refer to [manage access scopes](/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes).  
api_name: app-home
source_url:
  html: 'https://shopify.dev/docs/api/app-home/apis/scopes'
  md: 'https://shopify.dev/docs/api/app-home/apis/scopes.md'
---

# Scopes

The Scopes API provides the ability to dynamically manage your access scopes within an embedded context.

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).

## Scopes

Provides utilities to query, request, and revoke access scopes for the app using the Admin API.

* query

  () => Promise\<ScopesDetail>

  required

  Queries Shopify for the scopes for this app on this shop

* request

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

  required

  Requests the merchant to grant the provided scopes for this app on this shop

  This will open a [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) for the merchant to accept or decline the scopes.

* revoke

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

  required

  Revokes the provided scopes from this app on this shop

### ScopesDetail

* granted

  The scopes that have been granted on the shop for this app

  ```ts
  string[]
  ```

* optional

  The optional scopes that the app has declared in its configuration

  ```ts
  string[]
  ```

* required

  The required scopes that the app has declared in its configuration

  ```ts
  string[]
  ```

```ts
export interface ScopesDetail {
  /**
   * The scopes that have been granted on the shop for this app
   */
  granted: Scope[];
  /**
   * The required scopes that the app has declared in its configuration
   */
  required: Scope[];
  /**
   * The optional scopes that the app has declared in its configuration
   */
  optional: Scope[];
}
```

### ScopesRequestResponse

* detail

  ```ts
  ScopesDetail
  ```

* result

  ```ts
  UserResult
  ```

```ts
export interface ScopesRequestResponse {
  result: UserResult;
  detail: ScopesDetail;
}
```

### UserResult

\`UserResult\` represents the results of a user responding to a scopes request, i.e. a merchant user’s action taken when presented with a grant modal.

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

### ScopesRevokeResponse

* detail

  ```ts
  ScopesDetail
  ```

```ts
export interface ScopesRevokeResponse {
  detail: ScopesDetail;
}
```

## Examples

Examples for using App Bridge's Scopes API methods

### Query

Query access scopes granted to the app on this store

### Examples

* #### Query access scopes granted to the app on this store

  ##### Default

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

### Request

Request the user to grant access to the \`read\_products\` scope

### Examples

* #### Request the user to grant access to the \`read\_products\` scope

  ##### Default

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

  if (response.result === 'granted-all') {
    // merchant has been granted access — continue
    ...
  }
  else if (response.result === 'declined-all') {
    // merchant has declined access — handle accordingly
    ...
  }
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/app-home/requestmodal.png)

### Revoke

Revoke the granted access to the \`read\_products\` scope

### Examples

* #### Revoke the granted access to the \`read\_products\` scope

  ##### Default

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

## 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)