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.

Anchor to scopesScopes

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

Anchor to query query () => Promise<> required: Queries Shopify for the scopes for this app on this shop
Anchor to request request (scopes: string[]) => Promise<> required: Requests the merchant to grant the provided scopes for this app on this shop

This will open a permission grant modal for the merchant to accept or decline the scopes.
Anchor to revoke revoke (scopes: string[]) => Promise<> required: Revokes the provided scopes from this app on this shop

Scopes

The Scopes API enables embedded apps and extensions to request merchant consent for access scopes.

query
Queries Shopify for the scopes for this app on this shop
```
() => Promise<ScopesDetail>
```
request
Requests the merchant to grant the provided scopes for this app on this shop This will open a [permission grant modal](/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.
```
(scopes: string[]) => Promise<ScopesRequestResponse>
```
revoke
Revokes the provided scopes from this app on this shop
```
(scopes: string[]) => Promise<ScopesRevokeResponse>
```

export interface Scopes {
  /**
   * Queries Shopify for the scopes for this app on this shop
   */
  query: () => Promise<ScopesDetail>;

  /**
   * Requests the merchant to grant the provided scopes for this app on this shop
   *
   * This will open a [permission grant modal](/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.
   */
  request: (scopes: Scope[]) => Promise<ScopesRequestResponse>;

  /**
   * Revokes the provided scopes from this app on this shop
   */
  revoke: (scopes: Scope[]) => Promise<ScopesRevokeResponse>;
}

ScopesDetail

granted
The scopes that have been granted on the shop for this app
```
string[]
```
optional
The optional scopes that the app has declared in its configuration
```
string[]
```
required
The required scopes that the app has declared in its configuration
```
string[]
```

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
```
ScopesDetail
```
result
```
UserResult
```

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.

'granted-all' | 'declined-all'

ScopesRevokeResponse

detail
```
ScopesDetail
```

export interface ScopesRevokeResponse {
  detail: ScopesDetail;
}

Was this section helpful?

Anchor to examplesExamples

Examples for using App Bridge's Scopes API methods

Anchor to example-queryQuery

Anchor to example-query-access-scopes-granted-to-the-app-on-this-storeQuery access scopes granted to the app on this store

Was this section helpful?

Query access scopes granted to the app on this store

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

Anchor to example-requestRequest

Anchor to example-request-the-user-to-grant-access-to-the-`read_products`-scopeRequest the user to grant access to the `read_products` scope

Was this section helpful?

Request the user to grant access to the `read_products` scope

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

...

}

examples

Request the user to grant access to the `read_products` scope

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

Anchor to example-revokeRevoke

Anchor to example-revoke-the-granted-access-to-the-`read_products`-scopeRevoke the granted access to the `read_products` scope

Was this section helpful?

Revoke the granted access to the `read_products` scope

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

Anchor to relatedRelated

ReferenceManaging Access Scopes

APIRemix Scopes API