What is the difference between allowed_navigation_hosts and allowed_sources in shopify.app.toml?

Use allowed_navigation_hosts for external hosts you control that your app links customers to, which lets Shopify skip the exit interstitial. Use allowed_sources for external servers, such as your API or CDN, that your app's code loads from or sends requests to on storefront, checkout, or Shopify admin pages.

Why did Shopify reject my shopify app deploy after adding network_access?

Shopify checks both lists when creating the app version and rejects the deploy if an entry violates the network_access reference rules. Entries in allowed_navigation_hosts must be lowercase host names with no scheme, port, path, or wildcard, and must not be IP addresses, localhost, or Shopify domains like myshopify.com or shopifycdn.com. Entries in allowed_sources must be HTTPS origins.

Does declaring allowed_sources in shopify.app.toml enable fetch() in a checkout UI extension?

Not on its own: to call fetch(), a checkout UI extension also requires the network_access capability declared inside its own shopify.extension.toml file.

Shopify Secure Your App: network_access in shopify.app.toml

You can now secure your Shopify app by declaring external hosts and servers inside a new [network_access] section of shopify.app.toml. Any app whose code links to or contacts external servers from a storefront, checkout, or the Shopify admin can use this new configuration section.

What changed in shopify.app.toml?

Shopify app network access declarations let developers list external navigation hosts and request sources in shopify.app.toml. According to the Shopify changelog on network access hosts in shopify.app.toml, you can declare external hosts and servers in a new [network_access] section.

When a customer follows an external link from an online store, Shopify can show an exit interstitial telling them they are leaving the store. As documented in the Shopify CLI app configuration reference, listing the hosts that your app links to causes Shopify to skip the interstitial for links to them. Links pointing to these declared hosts skip that warning, though Shopify still blocks any host it identifies as malicious even if an app lists it.

Audit your external domains and clean up formatting before adding these declarations. Why does the order of operations matter here? According to the Shopify guide on declaring network access, Shopify checks both lists when creating the app version and rejects the deploy if an entry breaks the network_access rules.

If you treat allowed_navigation_hosts and allowed_sources as interchangeable, entries in the wrong format will fail the deploy, and links to undeclared hosts will still show the exit interstitial. Separate customer-facing link destinations from background server endpoints in your configuration file, just as teams maintain equivalent allowlists inside eCommerce security headers.

Who does the [network_access] configuration affect?

Any app whose code links to or contacts external servers from a storefront, checkout, or the Shopify admin can use the new section. Your declarations apply to every store that has your app installed, after you deploy and release a version that includes them.

We advise treating this configuration as part of your standard release hygiene, alongside your Shopify CLI engineering workflows. Because a single version release updates the rules across every store with your app installed, you avoid per-merchant configuration drift.

For all apps, Shopify strongly recommends adding customer link hosts to allowed_navigation_hosts and code request servers to allowed_sources. Once both lists are in place, run shopify app deploy and release the new version.

Which option beats which depends on how the browser interacts with the external endpoint. Putting an API server into allowed_navigation_hosts will not cover code requests, while putting a customer link destination into allowed_sources will not skip the exit interstitial. Use allowed_navigation_hosts for links from the online store and only list hosts that you control, such as your app's own domain.

Conversely, if your app's code loads from or sends requests to other servers on storefront, checkout, or Shopify admin pages, list those servers in allowed_sources. This list is where you add the servers your app's code contacts, such as your API or CDN.

Take a concrete example using an app hosted at app.example.com. If a storefront link sends customers to app.example.com, place app.example.com in allowed_navigation_hosts so Shopify skips the exit interstitial. If another customer link points to a payment page at pay.app.example.com, you must also add pay.app.example.com to allowed_navigation_hosts because app.example.com doesn't cover pay.app.example.com. Meanwhile, if your extension script calls fetch() against your API or loads from your CDN on checkout or storefront pages, put those servers in allowed_sources instead.

Leave out anything that Shopify serves, such as the files in a theme app extension's assets folder. Leave out your app proxy URL too, because the store serves app proxy pages from its own domain, and don't use Shopify domains like myshopify.com or shopifycdn.com.

Decision rules for [network_access] declarations

If your app links customers to an external host you control (such as app.example.com), then add that host to allowed_navigation_hosts so Shopify skips the exit interstitial.
If your app's code loads from or sends requests to an external server (such as your API or CDN) on storefront, checkout, or admin pages, add it to allowed_sources.
If a link points to a subdomain (such as pay.app.example.com), then list that subdomain explicitly because app.example.com doesn't cover pay.app.example.com.
If the resource is served by Shopify (such as a theme app extension's assets folder, an app proxy URL, myshopify.com, or shopifycdn.com), leave it out of your lists.
If a checkout UI extension needs to call fetch(), then also declare the network_access capability in its own shopify.extension.toml file.

How to implement network_access rules in your app

Each host in allowed_navigation_hosts must be a lowercase host name with no scheme, port, path, or wildcard, such as app.example.com, while each entry in allowed_sources is an HTTPS origin, such as https://api.app.example.com. Shopify checks both lists when it creates the app version, and rejects the deploy if an entry doesn't follow the rules in the network_access reference.

Subdomain scoping catches teams out if they assume root domains cascade, so list every host that your links point to, including subdomains. For example, app.example.com doesn't cover pay.app.example.com, though you only need to list each host and source once however many parts of your app use it.

If you build Shopify checkout UI extensions, updating the root app configuration is only part of the setup. To call fetch(), a checkout UI extension also needs the network_access capability in its own shopify.extension.toml file.

Audit your customer-facing links. Add the hosts that your app links customers to, such as your app's own site, to allowed_navigation_hosts, listing only hosts that you control.
Declare your external API and CDN endpoints. Add the servers that your app's code loads from or sends requests to on storefront, checkout, or Shopify admin pages to allowed_sources.
Format and deduplicate every host entry. Write navigation hosts as lowercase host names with no scheme, port, path, or wildcard, write sources as HTTPS origins, include every subdomain, and list each host and source once.
Strip out Shopify-served resources. Leave out theme app extension assets, your app proxy URL, and Shopify domains such as myshopify.com or shopifycdn.com.
Configure checkout extension capabilities. Enable the network_access capability in shopify.extension.toml if a checkout UI extension needs to call fetch().
Deploy and release the app version. Run shopify app deploy and release the new version so your declarations apply to every store with your app installed.

Where to start this week

Inspect your codebase for every external URL your storefront, checkout, and admin surfaces reference. Separate those URLs into customer navigation targets that you control and background servers that your code requests data from.

Before you run the deployment command in your terminal, verify that every host entry in allowed_navigation_hosts is lowercase and stripped of schemes, ports, paths, and wildcards. Double-check that no Shopify domains, app proxy URLs, or theme extension asset paths have crept in, and verify that every required subdomain has its own entry.

If your team maintains multiple extensions across storefront, checkout, and admin surfaces and wants an engineering partner to review your app architecture, bring us in for Shopify app development.