Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 55 ยท Authentication and Sessions

Managed Installation and Access Scopes

Learn how a Shopify app declares access scopes in shopify.app.toml, how managed installation asks merchants for consent, and how to keep scopes minimal and safe to change.

Every Shopify app starts life with no power at all. It cannot read a single product until a merchant says it may. The thing the merchant agrees to is a list of access scopes: short names such as read_products or write_orders that describe which parts of the store's data your app can touch. Scopes are the contract between your app and the merchant, and they decide which API calls will succeed once you hold an access token.

In the old days you built the consent screen yourself, by sending the merchant to a URL with a scope parameter (the flow in The OAuth Authorization Code Flow). Today Shopify handles that for you. You declare scopes in your app configuration, and Shopify shows the consent screen, stores the grant and tells your app what was approved. This is called managed installation. This lesson covers how to declare scopes, how optional scopes and scope changes behave, and why asking for less is almost always the right call.

The platform code in this lesson (TOML, App Bridge and GraphQL calls) is shown in read-only blocks, because the site cannot reach a real Shopify store. The runnable examples are small stand-ins written in plain JavaScript that model the same ideas. Names and behaviors follow Shopify's configuration as of the 2026 API versions; always confirm details in the current Shopify documentation before you ship.

What a scope looks like

A scope is a string made of an access level, an underscore and a resource: read_products, write_products, read_customers, write_draft_orders. Two rules cover most of what you need:

  • read_ lets you query; write_ lets you change. A write_ scope also includes the matching read access, so you do not need to list both read_products and write_products. Listing only write_products is enough.
  • Scopes are per resource. read_products says nothing about orders. If your code touches a resource, the scope for that resource must have been granted.

Some data needs more than a scope. For example, reading personal customer details on orders is protected customer data, which requires extra approval from Shopify (see Orders, Customers and Protected Data). A scope is necessary for such data, but not always sufficient.

Declaring scopes in the app configuration

Your app's configuration lives in shopify.app.toml (see App Configuration with shopify.app.toml). The scopes sit in the [access_scopes] table:

TOML
# shopify.app.toml (excerpt, read-only)
client_id = "your-client-id"
name = "Stock Notes"
application_url = "https://stock-notes.example.com"
embedded = true

[access_scopes]
# Required: the merchant must approve these to install.
scopes = "read_products,write_inventory"
# Optional: the merchant may decline these, and you can ask later.
optional_scopes = [ "read_orders" ]
use_legacy_install_flow = false

Three keys matter here:

  • scopes is a comma-separated string of required scopes. A merchant cannot install the app without accepting all of them.
  • optional_scopes is a list of scopes the merchant can decline at install time. Your app can ask for them later, when the merchant first uses the feature that needs them.
  • use_legacy_install_flow = false turns on managed installation. When it is false (the default for new apps), Shopify computes the consent screen from your TOML file. When it is true, your own code must run the OAuth redirects.

After you edit the file, shopify app deploy publishes a new app version containing the new scope list. Nothing changes for merchants until a version is released.

flowchart LR
  A["Edit scopes in<br/>shopify.app.toml"] --> B["shopify app deploy<br/>creates an app version"]
  B --> C["Merchant installs<br/>or opens the app"]
  C --> D{"All required scopes<br/>already granted?"}
  D -->|Yes| E["App works as before"]
  D -->|No| F["Shopify shows a consent<br/>screen for the new scopes"]
  F --> E

With managed installation, Shopify compares the granted scopes to your declared scopes and asks for consent only when something is missing.

What the merchant sees

During installation the merchant gets a screen listing, in plain language, what your app will be able to see and do. Because the screen is generated from your scope list, a long list of broad scopes produces a long and scary page, and merchants do abandon installs because of that. Shopify's app review also checks that you request only scopes you really use (see App Store Requirements and Review).

Least privilege: ask only for what you use

The principle of least privilege says a program should hold only the permissions it needs. For apps this pays off three times:

  1. Trust. A short consent screen converts better than a long one.
  2. Blast radius. If your database leaks, an attacker holding tokens that can only read products can do far less than one holding write_orders.
  3. Fewer reviews of your changes. Every new scope you add forces a re-consent step for every merchant who already installed the app.

Practical habits:

  • Start with read scopes and add write scopes only for features that change data.
  • Put a scope in optional_scopes when a feature is used by only some merchants.
  • Remove scopes you no longer use. Removing is cheap; the grant on existing installations is simply no longer required by new versions.
  • Review the scope list every time a feature ships or is deleted.

Optional scopes at runtime

When a merchant first uses a feature that needs an optional scope, your embedded app can ask for it from the browser using App Bridge. The API lives on the global shopify object:

JavaScript
// In the embedded app's browser code (read-only)
const { granted } = await shopify.scopes.query();
// granted is an array of scope handles, for example ["read_products", "write_inventory"]

if (!granted.includes("read_orders")) {
  const response = await shopify.scopes.request(["read_orders"]);
  // Shopify shows a consent dialog; the result says whether the merchant approved.
}

From the server you can also check what an installation currently has, using the Admin GraphQL API:

GRAPHQL
# Admin GraphQL API (read-only example; use a recent stable version)
query CurrentScopes {
  currentAppInstallation {
    accessScopes {
      handle
    }
  }
}

Always design the feature so it degrades gracefully when the merchant says no: hide the orders panel, show an explanation, and keep the rest of the app working. A scope that can be refused is a scope your code must be able to live without.

Changing scopes safely

Scope changes are where apps most often break, so treat them like a database migration:

  • Adding a required scope means existing merchants must approve it before your app can use it. Until they do, calls that need it fail with an access error. Prefer adding it as an optional scope and asking at the moment of need.
  • Adding code before the grant exists is a classic bug. If you deploy code that calls read_orders data to everyone while only some merchants granted the scope, the others will see errors. Guard every use with a scope check.
  • Removing a scope is safe for the app, but make sure no code path still depends on it.
  • Tokens and scopes are linked. An access token carries the scopes granted when it was issued. After a merchant approves new scopes, make sure your code works with the token that matches the new grant. With token exchange (see Token Exchange and Access Tokens) a fresh exchange returns a token for the currently granted scopes.

When your app starts, compare the scopes in your config with the scopes the installation reports. Log any gap loudly in development. A "missing scope" bug is far cheaper to find on a development store than in a merchant's support ticket.

A runnable scope-diff tool

The next stand-in models the comparison Shopify performs for you: required scopes versus granted scopes, with the rule that write_x includes read_x.

Node.js Scope diff: what is missing, what is extra

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The second line shows the re-consent case: read_customers is missing, so the merchant must approve before the app can use it. The third shows that a granted write_products already satisfies a required read_products. The last one shows an extra grant, which is harmless for the app but a sign that your config can be tightened on the next deploy.

An audit for least privilege

You can also check your own code against your config. Here each feature declares the scopes it needs, and the audit reports which declared scopes no feature uses.

Node.js Find scopes no feature needs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

write_products is reported as used only because the audit treats write_ as covering read_, and two features need read_products; in a real review you would notice that no feature writes products and replace it with read_products. read_customers is flagged as unused and should be removed. read_orders is used only by an optional feature, so it belongs in optional_scopes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which key in shopify.app.toml lists scopes a merchant is allowed to decline during installation?

    scopes holds the required list; optional_scopes holds scopes the merchant may refuse, which your app can request later when a feature needs them.
  2. 2. Your TOML requires write_products. Do you also need to list read_products?

    A write_ scope includes the matching read_ access, so listing only the write scope is enough.
  3. 3. You add a new required scope and deploy. What happens for merchants who already installed the app?

    Adding a required scope forces a consent step for existing installations. Until a merchant approves, calls that need the scope fail, so prefer optional scopes plus a check at the moment of need.
  4. 4. Why does least privilege matter for apps?

    A shorter consent screen helps installs, and tokens with fewer permissions can do less harm if they are exposed.

Summary

  • Scopes such as read_products or write_orders are the permissions a merchant grants to your app.
  • Declare them in the [access_scopes] table of shopify.app.toml; scopes is required, optional_scopes can be declined, and use_legacy_install_flow = false enables managed installation.
  • A write_ scope includes the matching read_ access.
  • shopify app deploy publishes the scope list; Shopify asks for consent only when the granted scopes fall short.
  • Request optional scopes at the moment of need with App Bridge, and make features degrade gracefully if refused.
  • Ask for the minimum, audit regularly, and treat scope changes like migrations.

Next: Session Tokens for Embedded Apps shows how your embedded app proves who is calling it, without cookies.