---
title: Scopes
description: |-
  Contains functions used to manage scopes for your app.

  This object is returned on authenticated Admin requests.
api_version: v4 latest
api_name: shopify-app-remix
source_url:
  html: 'https://shopify.dev/docs/api/shopify-app-remix/latest/apis/scopes'
  md: 'https://shopify.dev/docs/api/shopify-app-remix/latest/apis/scopes.md'
---

# Scopes

Contains functions used to manage scopes for your app.

This object is returned on authenticated Admin requests.

## scopes

Provides utilities that apps can use to [manage scopes](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation/manage-access-scopes) for the app using the Admin API.

* query

  () => Promise\<ScopesDetail>

  required

  Queries Shopify to see what scopes have been granted

* request

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

  required

  Requests the merchant grant the provided scopes

  This method performs a redirect to the grant screen.

* revoke

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

  required

  Revokes the provided scopes

  Warning: This method throws an [error](https://shopify.dev/docs/api/admin-graphql/unstable/objects/AppRevokeAccessScopesAppRevokeScopeError) if the provided optional scopes contains a required scope.

### 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[];
}
```

### ScopesRevokeResponse

* revoked

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

  ```ts
  string[]
  ```

```ts
export interface ScopesRevokeResponse {
  /**
   * The scopes that have been revoked on the shop for this app
   */
  revoked: Scope[];
}
```

Examples

### Examples

* #### Query for granted scopes

  ##### Description

  Call \`scopes.query\` to get scope details.

  ##### /app.\_index.tsx

  ```typescript
  import { authenticate } from "../shopify.server";
  import { json } from "@remix-run/node";

  export const loader = async ({ request }) => {
    const { scopes } = await authenticate.admin(request);
    const { required, optional, granted } = await scopes.query();

    if (granted.includes("write_products")) {
      // do something
    }

    return null
  };
  ```

* #### Ask the merchant to grant the provided scopes

  ##### Description

  Call \`scopes.request\` to request optional scopes.

  ##### /app/routes/app.request.tsx

  ```typescript
  import { authenticate } from "../shopify.server";

  // Example of an action to request optional scopes
  export const action = async ({ request }) => {
    const { scopes } = await authenticate.admin(request);
    const { granted } = await scopes.query();

    if (!granted.includes("write_products")) {
      await scopes.request(["write_products"]);
    }

    return null
  };
  ```

* #### Revoke optional scopes

  ##### Description

  Call \`scopes.revoke\` to revoke optional scopes.

  ##### /app.\_index.tsx

  ```typescript
  import { authenticate } from "../shopify.server";
  import { json } from "@remix-run/node";

  // Example of an action to POST optional scopes to revoke
  export const action = async ({ request }) => {
    const { scopes } = await authenticate.admin(request);
    const { granted } = await scopes.query();

    if (granted.includes("write_products")) {
      const revokedResponse = await scopes.revoke(["write_products"]);
      return json(revokedResponse);
    }

    return null
  };
  ```

## Related

[Authenticate requests from Shopify Admin. - Admin context](https://shopify.dev/docs/api/shopify-app-remix/authenticate/admin)