Choose a version:

AccessScope

object

A permission that controls access to GraphQL Admin API or Storefront API types. Each scope defines what data an App can read or write, following the format {action}_{resource} where action is typically "read" or "write".

Apps declare required and optional access scopes in their configuration. During installation, merchants review and grant these permissions, determining what shop data the app can access. The granted scopes remain active until the merchant uninstalls the app or revokes them. Apps can programmatically revoke their own dynamically granted optional scopes using appRevokeAccessScopes.

Anchor to FieldsFields

Anchor to descriptiondescription •String! non-null: A description of the actions that the access scope allows an app to perform.
Anchor to handlehandle •String! non-null: A readable string that represents the access scope. The string usually follows the format {action}_{resource}. {action} is read or write, and {resource} is the resource that the action can be performed on. {action} and {resource} are separated by an underscore. For example, read_orders or write_products.

Was this section helpful?

Anchor to MutationsMutations

Anchor to appDowngradeAccessScopes appDowngradeAccessScopes

•mutation

Downgrades granted optional write access scopes to their matching read access scopes. For example, downgrading write_products removes write_products and keeps read_products, so the app can keep reading products without asking the merchant to grant read_products again.

Revoking a write scope with appRevokeAccessScopes also removes its read access when the read scope was only granted through the write scope. Use this mutation instead when the app still needs read access.

The mutation always acts on the calling app's own installation on the shop. Only write scopes that the app declares as optional can be downgraded. Required scopes can't be downgraded. Write scopes that aren't currently granted are ignored.

Learn more about managing app permissions.

Show payload

Anchor to scopesscopes •[String!]! required: The handles of the write scopes to downgrade, for example write_products. Each granted write scope is replaced with its matching read scope.

Anchor to appRevokeAccessScopes appRevokeAccessScopes

•mutation

Revokes previously granted access scopes from an app installation, allowing merchants to reduce an app's permissions without completely uninstalling it. This provides granular control over what data and functionality apps can access.

For example, if a merchant no longer wants an app to access customer information but still wants to use its inventory features, they can revoke the customer-related scopes while keeping inventory permissions active.

Use the appRevokeAccessScopes mutation to:

Remove specific permissions from installed apps
Maintain app functionality while minimizing data exposure

The mutation returns details about which scopes were successfully revoked and any errors that prevented certain permissions from being removed.