Write_app_proxy as an optional_scope

Authentication & Access
1

Hi Shopify team,

I’m building a public app that uses an app proxy configured via shopify.app.toml, and I’d like to confirm the officially supported behavior around optional scopes and proxy configuration.

From the docs:

My intended setup is:

[access_scopes]
# Baseline permissions for core functionality
scopes = "whatever"

# App proxy is optional, used only for the storefront feature
optional_scopes = "write_app_proxy"

[app_proxy]
url = "/storefront-portal"
prefix = "apps"
subpath = "portal"

This is an existing app that doesn’t currently use app_proxy. The feature would only be used after the merchant completes a specific onboarding on the Dashboard, so the optional nature of the scope would be appropriate..

Question:

For a shop that has already installed my app without write_app_proxy:

  1. Would the [app_proxy] entry even be accepted if we don’t have write_app_proxy among the regular scopes?
  2. If I later request write_app_proxy as an optional scope and the merchant approves it,
  • does Shopify automatically apply the [app_proxy] configuration from shopify.app.toml for that existing installation?
  • Or, is there an additional step (either via the Partner Dashboard, Admin UI, or an API) that I must perform to ensure the app proxy is actually configured for that shop once the scope is granted?
  1. More generally, is there any documented guarantee or contract about how [app_proxy] in shopify.app.toml is applied to:
  • New installs (when write_app_proxy is not granted at install time), and
  • Existing installs that only grant write_app_proxy later through the optional scopes flow?

I want to make sure I’m not relying on documented features and not unintended bugs.

Thanks in advance for clarifying how this is intended to work.

Best regards,
Ferenc

2

Hi @ferenc

Your TOML configuration is syntactically valid, and shopify app deploy should accept the [app_proxy] section alongside write_app_proxy in optional_scopes. However, the app proxy docs state that “configuring an app proxy requires the write_app_proxy access scope,” and the getting-started guide only shows it in the required scopes field. This means for shops that install your app without granting write_app_proxy, the proxy route almost certainly won’t be active.

I’d recommend testing this on a dev store: install without granting write_app_proxy, then request it via shopify.scopes.request(['write_app_proxy']) and check whether the proxy route becomes active. If it doesn’t activate retroactively, a practical alternative would be keeping write_app_proxy in the required scopes and gating the storefront feature at the application level (only showing it after onboarding) rather than relying on optional scopes to control the proxy configuration itself.

3

Hi @Liam-Shopify ,

Thanks for the quick answer!

This is fine, I also recognize this as the expected behavior.

I’d like to avoid relying on functionality that ‘happens to work’ but is not officially supported or covered with tests on Shopify’s side. Is there a chance someone on Shopify’s end could verify if activating routes on write_app_proxy scope grants is the expected behavior?

My understanding is that this would result in prompting all existing users to grant this feature. Our userbase is very large, and we’d like to avoid this disruption if possible given that most users would not be using the new feature we’re adding, at least initially.

Do you mean that it’s possible to write app_proxy configurations via the API instead of the toml once scopes are granted? I haven’t yet found a way to do that.