After you've enabled [Shopify managed install](/docs/apps/build/authentication-authorization/app-installation), you can manage your app's [access scopes](/docs/api/usage/access-scopes).
> Note: If you're still using the legacy installation and OAuth authorization code grant flow,
> then refer to the [authorization code grant](/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant#manage-access-scopes) guide on managing access scopes instead.
## Access scope configurations
There are two ways you can [configure your access scopes](docs/apps/build/cli-for-apps/app-configuration#access_scopes):
| Configuration | Description |
|------------|-------------|
| `scopes` | These configured access scopes are mandatory when merchants install your app with [Shopify managed install](/docs/apps/build/authentication-authorization/app-installation). Merchants **must** grant access before your app can be installed. Your app is guaranteed to have these access scopes after it's installed on the merchant's store. |
| `optional_scopes` | Unlike required scopes, optional scopes can only be requested by the app post-installation. When requested, merchants have the option to grant access to these scopes, or to decline them. Merchants can also revoke previously granted optional scopes. Optional scopes are useful if you want to provide certain features to different stores, without forcing every app install to provide the same data access. |
### Scopes
The required access scopes are defined in the `scopes` field of your app's TOML file:
When a merchant installs your app, they're prompted to grant permission to **all** the access scopes that you've defined in the `scopes` field.
After the app is installed, it's guaranteed to have the required access scopes.
### Optional scopes
The access scopes that can be [requested dynamically](#request-new-access-scopes-dynamically) are defined in the `optional_scopes` field of the app's TOML file:
When a merchant installs your app, they're not prompted during installation to grant permission to the access scopes that you've defined in the `optional_scopes` field.
The [app initiates the request](#request-new-access-scopes-dynamically) to gain access to these scopes after the installation is complete, if necessary.
## Modify declared scopes
To declare more or fewer access scopes for your app, update your app's [configuration TOML file](docs/apps/build/cli-for-apps/app-configuration#access_scopes) and deploy the changes.
1. Modify the `scopes` or `optional_scopes` fields in your app's TOML file to include the desired set of access scopes.
2. Deploy the access scope changes by running the following Shopify CLI command:
3. (Optional). Subscribe to the [app/scopes_update](/docs/api/webhooks/latest?reference=toml#list-of-topics-app/scopes_update) topic to receive webhooks when the granted scopes are updated.
#### Modifying the `scopes` field
If you modified the `scopes` field, then the following behavior occurs:
- Merchants will be prompted to approve the updated access scopes when they open your app.
- The `app/scopes_update` webhook will be triggered when the merchant approves the access scope changes.
- If the change is a reduction of scopes, the merchant won't be prompted and the app will lose access to the scopes automatically when the merchant opens the app.
- The `app/scopes_update` webhook will be triggered when the user opens the app.
#### Modifying the `optional_scopes` field
If you modify the `optional_scopes` field, then the following behavior occurs:
- Your app can now start [requesting the new access scopes](#request-new-access-scopes-dynamically).
- The granted access scopes for your app installation won't change until your app requests for the new access scopes dynamically and the
merchant grants your app access to the newly updated scopes.
- The `app/scopes_update` webhook will be triggered when the merchant approves the access scope changes.
## Query currently granted scopes
You can use [GraphQL queries](/docs/api/admin-graphql/latest/queries/currentAppInstallation) to get the currently granted access scopes for your app installation.
### Shopify API libraries
You can also use the following helper methods in Shopify's API libraries to query for the currently granted access scopes:
| Library | Method |
|---|--------|
| App Bridge API | [shopify.scopes.query()](/docs/api/app-bridge-library/apis/scopes#scopes-propertydetail-query) |
| Remix API | [scopes.query()](/docs/api/shopify-app-remix/latest/apis/scopes#scopes-propertydetail-query) |
## Request new access scopes dynamically
> Note:
> You can only request additional access scopes dynamically if they are configured as `optional_scopes` in your app's TOML file, and if the configuration changes have been deployed.
> Access scopes configured in the `scopes` field can't be requested dynamically.
### Request access scopes using the App Bridge API for embedded apps
If you're building an embedded app, then you should use the [App Bridge scopes API](/docs/api/app-bridge-library/apis/scopes#scopes-propertydetail-request) to request new access scopes dynamically.
This method **doesn't require a browser redirect** and can be performed on the client side of an embedded app.
This asynchronous, client-side method displays a permission grant modal for the access scopes requested,
on top of your running embedded app.
Example permission grant modal:
### Request access scopes using a request URL for non-embedded apps
To request optional scopes dynamically for a non-embedded app, you can direct the merchant to the request URL so they can grant approval to the new access scopes.
| Query parameter | Description |
|---|---|
| `STORE_NAME` | The name of the merchant's store |
| `CLIENT_ID` | The app's client ID |
| `REQUESTED_SCOPES` | A comma separated list of access scopes to request. This must be a subset of the declared `optional_scopes` in your TOML file. |
Example request URL:
```
https://admin.shopify.com/store/my-cool-store/oauth/install?client_id=a61950a2cbd5f32876b0b55587ec7a27&optional_scopes=read_discounts,write_products
```
### Shopify API libraries
You can use the following helper methods in Shopify's API libraries to request for new access scopes dynamically:
| Library | Method | Description |
|---|--------|------|
| App Bridge API | [shopify.scopes.request()](/docs/api/app-bridge-library/apis/scopes#scopes-propertydetail-request) | This asynchronous, client-side method displays a permission grant modal for the access scopes requested, on top of your running embedded app. |
| Remix API | [scopes.request()](/docs/api/shopify-app-remix/latest/apis/scopes#scopes-propertydetail-request) | This is recommended for non-embedded apps and server side handling from a Remix app. |
## Revoke granted scopes dynamically
> Note:
> Only scopes configured as `optional_scopes` and that were [dynamically granted](#request-new-access-scopes-dynamically) can be revoked.
> Access scopes configured in the `scopes` field can't be revoked dynamically.
If your app no longer requires certain access scopes from a merchant's store, we recommend revoking the access scopes.
This helps to avoid a potential data leak, if the access token is ever compromised.
You can revoke access scopes by making a [GraphQL mutation](/docs/api/admin-graphql/latest/mutations/appRevokeAccessScopes).
### Shopify API libraries
You can use the following helper methods in Shopify's API libraries to revoke granted access scopes:
| Library | Method |
|---|--------|
| App Bridge API | [shopify.scopes.revoke()](/docs/api/app-bridge-library/apis/scopes#scopes-propertydetail-revoke) |
| Remix API | [scopes.revoke()](/docs/api/shopify-app-remix/latest/apis/scopes#scopes-propertydetail-revoke) |
## Developer tools and resources
