Update your embedded app OAuth flow

On August 23, 2022, we've updated the recommended method for authorizing embedded apps using OAuth. The new method improves performance, and eliminates screen flicker caused by the number and types of redirects.

In this section, you'll learn about our new recommendations for the OAuth flow, and their impact on your app. This section also includes tutorials that you can follow to update your existing apps to use the recommended method.

To learn whether your app should be updated, refer to affected apps.

Affected apps

Anchor link to section titled "Affected apps"

You should update your app OAuth flow if your app is embedded, and any of the following is true:

Your app was created before August 23, 2022, either using Shopify CLI, or using an app template.
Your app was created after August 23, 2022, but you didn't use Shopify CLI or an app template as a starting point.
Your app was created after August 23, 2022 using Shopify CLI, or using an app template, but you made significant changes to the OAuth flow.

Apps built after August 23, 2022 using Shopify CLI or using an app template already include an OAuth implementation that follows all of our OAuth performance best practices.

How it works

Anchor link to section titled "How it works"

Depending on the context, Shopify can render embedded apps in either an iframe or a WebView.

As a part of the OAuth process, a merchant needs to grant permission for your app to access store data. You can request these permissions by redirecting the the merchant to the grant screen, which is rendered inside the Shopify admin.

For security reasons, Shopify sets an X-Frame-Options: DENY parameter on the grant screen page. This prevents the page from being rendered inside an iframe. This means that, in specific circumstances, your app needs to escape the iframe that contains it so the merchant can be redirected to the grant screen.

Screenshot showing the Shopify OAuth installation permissions prompt asking the user to choose "Install app" or "Cancel".

Updates to recommendations

Anchor link to section titled "Updates to recommendations"

Shopify has updated its recommendations regarding when and how your app should escape the iframe, how the app redirects back to the iframe, and the information that's available when the app is loaded. These changes reduce the number of HTTP redirects and screen flickers that the user experiences.

The current recommendations are also included on our app performance best practices.

Previous recommendation	Current recommendation
To make sure that the grant screen isn't rendered inside the iframe, set a cookie, then perform a client-side redirect using Shopify App Bridge.	Check the `embedded` parameter to identify whether the app is rendered in an iframe.
Always perform a client-side redirect using Shopify App Bridge.	Perform a `3xx` server-side redirect only if the app isn't embedded.
To perform client-side redirects, load Shopify App Bridge from the Shopify CDN.	To perform client-side redirects, load Shopify App Bridge from the frontend app bundle.
Redirect to your app URL, then perform a client-side redirect to the embedded app URL using Shopify App Bridge.	Perform a server-side `3xx` redirect to the embedded app URL.