shopify_app 21.6.0 → 22.5.0

data/config/locales/pt-BR.yml

@@ -3,19 +3,3 @@ pt-BR:
   logged_out: Você saiu.
   could_not_log_in: Não foi possível fazer login na Shopify store
   invalid_shop_url: Domínio de loja inválido
-  enable_cookies_heading: Habilitar cookies de %{app}
-  enable_cookies_body: Você precisa habilitar manualmente os cookies neste navegador
-    para usar %{app} dentro da Shopify.
-  enable_cookies_footer: Os cookies permitem que o app o autentique armazenando temporariamente
-    suas preferências e dados pessoais. Eles expiram depois de 30 dias.
-  enable_cookies_action: Habilitar cookies
-  top_level_interaction_heading: Seu navegador precisa autenticar %{app}
-  top_level_interaction_body: Seu navegador exige que apps como o %{app} consultem
-    você sobre o acesso a cookies antes que a Shopify os abra.
-  top_level_interaction_action: Continuar
-  request_storage_access_heading: "%{app} precisa acessar cookies"
-  request_storage_access_body: Isso permite que o app autentique você armazenando
-    temporariamente seus dados pessoais. Clique em continuar e permita os cookies
-    para usar o app.
-  request_storage_access_footer: Os cookies expiram depois de 30 dias.
-  request_storage_access_action: Continuar

data/config/locales/pt-PT.yml

@@ -3,20 +3,3 @@ pt-PT:
   logged_out: Terminou a sessão com sucesso
   could_not_log_in: Não foi possível iniciar sessão na loja da Shopify
   invalid_shop_url: Domínio de loja inválido
-  enable_cookies_heading: Ativar cookies de %{app}
-  enable_cookies_body: Tem de ativar manualmente os cookies neste navegador para utilizar
-    %{app} dentro da Shopify.
-  enable_cookies_footer: Os cookies permitem que a aplicação o autentique armazenando
-    temporariamente as suas preferências e informações pessoais. Expiram ao fim de
-    30 dias.
-  enable_cookies_action: Ativar cookies
-  top_level_interaction_heading: O seu navegador tem de autenticar %{app}
-  top_level_interaction_body: O seu navegador exige que aplicações como %{app} lhe
-    solicitem o acesso de cookies, antes que a Shopify as possa abrir.
-  top_level_interaction_action: Continuar
-  request_storage_access_heading: "%{app} tem de aceder a cookies"
-  request_storage_access_body: Isto permite que a aplicação o autentique armazenando
-    temporariamente as suas informações pessoais. Clique em continuar e permita os
-    cookies para utilizar a aplicação.
-  request_storage_access_footer: Os cookies expiram ao fim de 30 dias.
-  request_storage_access_action: Continuar

data/config/locales/sv.yml

@@ -3,19 +3,3 @@ sv:
   logged_out: Har loggats ut
   could_not_log_in: Det gick inte att logga in i Shopify-butiken
   invalid_shop_url: Ogiltig butiksdomän
-  enable_cookies_heading: Aktivera cookies från %{app}
-  enable_cookies_body: Du måste aktivera cookies manuellt i den här webbläsaren för
-    att kunna använda %{app} inom Shopify.
-  enable_cookies_footer: Cookies låter appen autentisera dig genom att tillfälligt
-    lagra dina inställningar och personuppgifter. De upphör efter 30 dagar.
-  enable_cookies_action: Aktivera cookies
-  top_level_interaction_heading: Din webbläsare måste verifiera %{app}
-  top_level_interaction_body: Din webbläsare kräver att appar som %{app} frågar dig
-    om tillgång till cookies innan Shopify kan öppna den för dig.
-  top_level_interaction_action: Fortsätt
-  request_storage_access_heading: "%{app} behöver tillgång till cookies"
-  request_storage_access_body: Detta gör det möjligt för appen att autentisera dig
-    genom att tillfälligt lagra din personliga information. Klicka på fortsätt och
-    tillåta cookies att använda appen.
-  request_storage_access_footer: Cookies upphör efter 30 dagar.
-  request_storage_access_action: Fortsätt

data/config/locales/th.yml

@@ -3,18 +3,3 @@ th:
   logged_out: ออกจากระบบสำเร็จ
   could_not_log_in: ไม่สามารถเข้าสู่ระบบร้านค้า Shopify ได้
   invalid_shop_url: โดเมนร้านค้าไม่ถูกต้อง
-  enable_cookies_heading: เปิดใช้คุกกี้จาก %{app}
-  enable_cookies_body: คุณต้องเปิดใช้คุกกี้ด้วยตนเองในเบราว์เซอร์นี้เพื่อใช้งาน %{app}
-    ภายใน Shopify
-  enable_cookies_footer: คุกกี้ช่วยให้แอปตรวจสอบความถูกต้องของคุณด้วยการจัดเก็บความชื่นชอบและข้อมูลส่วนตัวของคุณชั่วคราว
-    คุกกี้จะหมดอายุหลังจาก 30 วัน
-  enable_cookies_action: เปิดใช้คุกกี้
-  top_level_interaction_heading: เบราว์เซอร์ของคุณต้องรับรองความถูกต้องของ %{app}
-  top_level_interaction_body: เบราว์เซอร์ของคุณต้องการแอปอย่าง %{app} เพื่อขอให้คุณเข้าถึงคุกกี้ก่อนที่
-    Shopify จะสามารถเปิดมันให้คุณได้
-  top_level_interaction_action: ดำเนินการต่อ
-  request_storage_access_heading: "%{app} ต้องการสิทธิ์การเข้าถึงคุกกี้"
-  request_storage_access_body: สิ่งนี้ช่วยให้แอปตรวจสอบความถูกต้องของคุณด้วยการจัดเก็บข้อมูลส่วนตัวของคุณชั่วคราว
-    คลิกดำเนินการต่อและอนุญาตให้คุกกี้ใช้แอป
-  request_storage_access_footer: คุกกี้จะหมดอายุหลังจาก 30 วัน
-  request_storage_access_action: ดำเนินการต่อ

data/config/locales/tr.yml

@@ -3,20 +3,3 @@ tr:
   logged_out: Oturum başarıyla kapatıldı
   could_not_log_in: Shopify mağazasında oturum açılamadı
   invalid_shop_url: Geçersiz mağaza alan adı
-  enable_cookies_heading: "%{app} uygulamasından çerezleri etkinleştir"
-  enable_cookies_body: "%{app} uygulamasını Shopify içinde kullanabilmek için bu tarayıcıda
-    çerezleri manuel olarak etkinleştirmelisiniz."
-  enable_cookies_footer: Çerezler, tercihlerinizi ve kişisel bilgilerinizi geçici
-    olarak saklayıp uygulamanın kimliğinizi doğrulamasına imkan tanır. Çerezlerin
-    süresi 30 gün sonra sonra sona erer.
-  enable_cookies_action: Çerezleri etkinleştir
-  top_level_interaction_heading: Tarayıcınızın %{app} kimliğini doğrulaması gerekiyor
-  top_level_interaction_body: Tarayıcınız, Shopify tarafından açılmadan önce %{app}
-    gibi uygulamaların sizden çerezlere erişim izni istemesini zorunlu tutuyor.
-  top_level_interaction_action: Devam
-  request_storage_access_heading: "%{app} uygulamasının çerezlere erişmesi gerekiyor"
-  request_storage_access_body: Böylece uygulama, kişisel bilgilerinizi geçici olarak
-    saklayıp kimliğinizi doğrulayabilir. Devam et'e tıklayın ve çerezlerin uygulamayı
-    kullanmasına izin verin.
-  request_storage_access_footer: Çerezlerin süresi 30 gün sonra sonra sona erer.
-  request_storage_access_action: Devam

data/config/locales/vi.yml

@@ -3,20 +3,3 @@ vi:
   logged_out: Đã đăng xuất thành công
   could_not_log_in: Không thể đăng nhập vào cửa hàng trên Shopify
   invalid_shop_url: Miền cửa hàng không hợp lệ
-  enable_cookies_heading: Bật cookie từ %{app}
-  enable_cookies_body: Bạn phải bật cookie trong trình duyệt này theo cách thủ công
-    để sử dụng %{app} trong Shopify.
-  enable_cookies_footer: Cookie cho phép ứng dụng xác thực bạn bằng cách tạm thời
-    lưu trữ tùy chọn và thông tin cá nhân của bạn. Những thông tin này sẽ hết hạn
-    sau 30 ngày.
-  enable_cookies_action: Bật cookie
-  top_level_interaction_heading: Trình duyệt của bạn cần xác thực %{app}
-  top_level_interaction_body: Trình duyệt của bạn cần các ứng dụng như %{app} để yêu
-    cầu quyền truy cập vào cookie thì Shopify mới có thể mở giúp bạn.
-  top_level_interaction_action: Tiếp tục
-  request_storage_access_heading: "%{app} cần quyền truy cập cookie"
-  request_storage_access_body: Nhờ vậy, ứng dụng có thể xác thực bạn bằng cách tạm
-    thời lưu trữ thông tin cá nhân của bạn. Nhấp vào tiếp tục và cho phép cookie sử
-    dụng ứng dụng.
-  request_storage_access_footer: Cookie sẽ hết hạn sau 30 ngày.
-  request_storage_access_action: Tiếp tục

data/config/locales/zh-CN.yml

@@ -3,14 +3,3 @@ zh-CN:
   logged_out: 已成功退出
   could_not_log_in: 无法登录到 Shopify 商店
   invalid_shop_url: 商店域名无效
-  enable_cookies_heading: 从 %{app} 启用 Cookie
-  enable_cookies_body: 您必须在此浏览器中手动启用 Cookie 才能在 Shopify 中使用 %{app}。
-  enable_cookies_footer: Cookie 使此应用能够通过暂时存储您的偏好设置和个人信息来验证您的身份。这些信息将在 30 天后过期。
-  enable_cookies_action: 启用 Cookie
-  top_level_interaction_heading: 您的浏览器需要对 %{app} 进行验证
-  top_level_interaction_body: 您的浏览器要求类似 %{app} 的应用向您申请访问 Cookie，之后 Shopify 才能为您打开它。
-  top_level_interaction_action: 继续
-  request_storage_access_heading: "%{app} 需要访问 Cookie"
-  request_storage_access_body: 这使此应用能够通过暂时存储您的个人信息来验证您的身份。点击继续并启用 Cookie 以使用此应用。
-  request_storage_access_footer: Cookie 将在 30 天后过期。
-  request_storage_access_action: 继续

data/config/locales/zh-TW.yml

@@ -3,14 +3,3 @@ zh-TW:
   logged_out: 登出成功
   could_not_log_in: 無法登入 Shopify 商店
   invalid_shop_url: 商店網域無效
-  enable_cookies_heading: 啟用 %{app} 的 Cookie
-  enable_cookies_body: 您必須在此瀏覽器中手動啟用 Cookie，才能夠在 Shopify 使用 %{app}。
-  enable_cookies_footer: Cookie 可讓應用程式暫時儲存您的偏好設定和個人資訊，藉此驗證您的身分，這些資料會在 30 天後失效。
-  enable_cookies_action: 啟用 Cookie
-  top_level_interaction_heading: 您的瀏覽器需要驗證 %{app}
-  top_level_interaction_body: 您的瀏覽器要求 %{app} 等應用程式向您請求 Cookie 的存取權限，才能讓 Shopify 為您開啟該應用程式。
-  top_level_interaction_action: 繼續
-  request_storage_access_heading: "%{app} 需要 Cookie 存取權限"
-  request_storage_access_body: Cookie 可讓應用程式暫時儲存您的個人資訊，藉此驗證您的身分。按一下繼續並允許 Cookie 使用此應用程式。
-  request_storage_access_footer: Cookie 將於 30 天後失效。
-  request_storage_access_action: 繼續

data/config/routes.rb

@@ -8,6 +8,7 @@ ShopifyApp::Engine.routes.draw do
     get login_url => :new, :as => :login
     post login_url => :create, :as => :authenticate
     get "logout" => :destroy, :as => :logout
+    get "patch_shopify_id_token" => :patch_shopify_id_token
 
     # Kept to prevent apps relying on these routes from breaking
     if login_url.gsub(%r{^/}, "") != "login"
@@ -26,6 +27,6 @@ ShopifyApp::Engine.routes.draw do
   end
 
   namespace :webhooks do
-    post ":type" => :receive
+    post "(:type)" => :receive
   end
 end

data/docs/Quickstart.md

@@ -34,8 +34,15 @@ HOST='https://some-random-words.trycloudflare.com/'
 
 ## Use Shopify App Bridge to embed your app in the Shopify Admin
 
-A basic example of using [*Shopify App Bridge*](https://shopify.dev/tools/app-bridge) is included in the install generator. An instance Shopify App Bridge is automatically initialized in [shopify_app.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/shopify_app.js). 
+A basic example of using [*Shopify App Bridge*](https://shopify.dev/tools/app-bridge) is included in the install generator. An instance Shopify App Bridge is automatically initialized in [shopify_app.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/shopify_app.js).
 
-The [flash_messages.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/flash_messages.js) file converts Rails [flash messages](https://api.rubyonrails.org/classes/ActionDispatch/Flash.html) to App Bridge Toast actions automatically. By default, this library is included via [unpkg in the embedded_app layout](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/embedded_app.html.erb#L27). 
+If you are using the `shopify_app` gem **without** the [frontend react template](https://github.com/Shopify/shopify-frontend-template-react), the [flash_messages.js](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/flash_messages.js) file converts Rails [flash messages](https://api.rubyonrails.org/classes/ActionDispatch/Flash.html) to App Bridge Toast actions automatically. If your app is embedded and you want to display flash messages you will need to update the session storage to allow for 3rd party cookies. So that the flash messages can be save in the session cookie.
+
+```ruby
+#session_store.rb
+Rails.application.config.session_store(:cookie_store, key: '_example_session', expire_after: 14.days, secure: true, same_site: 'None')
+```
+
+By default, this library is included via [unpkg in the embedded_app layout](https://github.com/Shopify/shopify_app/blob/master/lib/generators/shopify_app/install/templates/embedded_app.html.erb#L27).
 
 For more advanced uses it is recommended to [install App Bridge via npm or yarn](https://help.shopify.com/en/api/embedded-apps/app-bridge/getting-started#set-up-shopify-app-bridge-in-your-app).

data/docs/Troubleshooting.md

@@ -92,29 +92,6 @@ Edit `config/initializer/shopify_app.rb` and ensure the following configurations
 + config.shop_session_repository = 'Shop'
 ```
 
-#### Inspect server logs
-
-If you have checked the configurations above, and the app is still using cookies, then it is possible that the `shopify_app` gem defaulted to relying on cookies. This would happen when your browser allows third-party cookies and a session token was not successfully found as part of your request.
-
-In this case, check the server logs to see if the session token was invalid:
-
-```los
-[ShopifyApp::JWT] Failed to validate JWT: [JWT::<Error>] <Failure message>
-```
-
-*Example*
-
-```
-[ShopifyApp::JWT] Failed to validate JWT: [JWT::ImmatureSignature] Signature nbf has not been reached
-```
-
-**Note:** In a local development environment, you may want to temporarily update your `Gemfile` to point to a local instance of the `shopify_app` library instad of an installed gem. This will enable you to use a debugging tool like `byebug` to debug the library.
-
-```diff
-- gem 'shopify_app', '~> 14.2'
-+ gem 'shopify_app', path: '/path/to/shopify_app'
-```
-
 ### My app can't make requests to the Shopify API
 
 > **Note:** Session tokens cannot be used to make authenticated requests to the Shopify API. Learn more about authenticating your backend requests to Shopify APIs at [Shopify API authentication](https://shopify.dev/concepts/about-apis/authentication).

data/docs/Upgrading.md

@@ -8,6 +8,10 @@ This file documents important changes needed to upgrade your app's Shopify App v
 
 [Unreleased](#unreleased)
 
+[Upgrading to `v22.2.0`](#upgrading-to-v2220)
+
+[Upgrading to `v22.0.0`](#upgrading-to-v2200)
+
 [Upgrading to `v20.3.0`](#upgrading-to-v2030)
 
 [Upgrading to `v20.2.0`](#upgrading-to-v2020)
@@ -38,8 +42,67 @@ We also recommend the use of a staging site which matches your production enviro
 
 If you do run into issues, we recommend looking at our [debugging tips.](https://github.com/Shopify/shopify_app/blob/main/docs/Troubleshooting.md#debugging-tips)
 
+## Unreleased
+
+#### (v23.0.0) - Deprecated methods in CallbackController
+The following methods from `ShopifyApp::CallbackController` have been deprecated in `v23.0.0`
+- `perform_after_authenticate_job`
+- `install_webhooks`
+- `perform_post_authenticate_jobs`
+
+If you have overwritten these methods in your callback controller to modify the behavior of the inherited `CallbackController`, you will need to
+update your app to use configurable option `config.custom_post_authenticate_tasks` instead. See [post authenticate tasks](/docs/shopify_app/authentication.md#post-authenticate-tasks)
+for more information.
+
+#### (v23.0.0) - Removed `ShopifyApp::JWTMiddleware`
+The `ShopifyApp::JWTMiddleware` middleware has been removed in `v23.0.0`. This middleware was used to populate the following environment variables from the JWT session token:
+- `request.env["jwt.token"]`
+- `request.env["jwt.shopify_domain"]`
+- `request.env["jwt.shopify_user_id"]`
+- `request.env["jwt.expire_at"]`
+
+If you are using any of these variables in your app, you'll need to replace them. You can instead include the `ShopifyApp::WithShopifyIdToken` concern, which does the same JWT parsing as the middleware, and exposes the same values in the following helper methods:
+- `shopify_id_token`
+- `jwt_shopify_domain`
+- `jwt_shopify_user_id`
+- `jwt_expire_at`
+
+#### (v23.0.0) - Deprecated "ShopifyApp::JWT" class
+The `ShopifyApp::JWT` class has been deprecated in `v23.0.0`. Use [ShopifyAPI::Auth::JwtPayload](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/jwt_payload.rb)
+class from the `shopify_api` gem instead. A search and replace should be enough for this migration.
+  - `ShopifyAPI::Auth::JwtPayload` is a superset of the `ShopifyApp::JWT` class, and contains methods that were available in `ShopifyApp::JWT`.
+  - `ShopifyAPI::Auth::JwtPayload` raises `ShopifyAPI::Errors::InvalidJwtTokenError` if the token is invalid.
+
+## Upgrading to `v22.2.0`
+#### Added new feature for zero redirect embedded app authorization flow - Token Exchange
+A new embedded app authorization strategy has been introduced in `v22.2.0` that eliminates the redirects that were previously necessary for OAuth.
+It can replace the existing installation and authorization code grant flow.
+See [new embedded app authorization strategy](/README.md#new-embedded-app-authorization-strategy-token-exchange) for more information.
+
+## Upgrading to `v22.0.0`
+#### Dropped support for Ruby 2.x
+Support for Ruby 2.x has been dropped as it is no longer supported. You'll need to upgrade to 3.x.x
+
+#### Renamed Controller Concerns
+The following controller concerns have been renamed/replaced in `v21.10.0` and have now been removed. To upgrade, please rename any usage in your apps's controllers that include them to the following:
+
+|Old Deprecated Controller Concern |Replaced By New Controller Concern|
+|---|---|
+|`Authenticated`|`EnsureHasSession`|
+|`RequireKnownShop`|`EnsureInstalled`|
+
+The new names better reflect what assurances the including the controller concern provide. The new concern provide similar if not identical functionality as the concerns they replaced.
+
+#### Remove ScripttagManager
+Script tag usage has largely been replaced with the adoption of [theme app extensions](https://shopify.dev/docs/apps/online-store/theme-app-extensions) and [thank you order status customization](https://shopify.dev/docs/apps/checkout/thank-you-order-status). The manager has been removed with this major release due to effective replacement and a goal to have parity in supported functionality across language stacks.
+
+If you find yourself still using Scipt Tags and want to continue the pattern of declarative management of script tags this gem used to use, we recommend porting the logic [the manager used in prior versions](https://github.com/Shopify/shopify_app/blob/2336fabc6d0b45a4dee3f336455dace4d2d88bc4/lib/shopify_app/managers/scripttags_manager.rb#L4) and implementing it in a [post authentication job](https://github.com/Shopify/shopify_app/blob/main/docs/shopify_app/authentication.md#run-jobs-after-the-oauth-flow). This is the recommended flow to create script tags (or any other logic) for stores that install your app.
+
+#### No longer rescue non-shopify API errors during customized OAuth flow
+If you have customized authentication logic and are counting on the `CallbackController` to catch your error and redirect to login, you'll need to catch that error and redirect to `login_url_with_optional_shop`.
+
 ## Upgrading to 21.3.0
-The `Itp` controller concern has been removed from `LoginProtection` which is included by the `Authenticated` controller concern.
+The `Itp` controller concern has been removed from `LoginProtection` which is included by the `Authenticated`/`EnsureHasSession` controller concern.
 If any of your controllers are dependant on methods from `Itp` then you can include `ShopifyApp::Itp` directly.
 You may notice a deprecation notice saying, `Itp will be removed in an upcoming version`.
 This is because we intend on removing `Itp` completely in `v22.0.0`, but this will work in the meantime.

data/docs/shopify_app/authentication.md

@@ -1,41 +1,184 @@
 # Authentication
 
-The Shopify App gem implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) to get [access tokens](https://shopify.dev/concepts/about-apis/authentication#api-access-modes). These are used to authenticate requests made by the app to the Shopify API. 
+The Shopify App gem implements [OAuth 2.0](https://shopify.dev/tutorials/authenticate-with-oauth) to get [session tokens](https://shopify.dev/concepts/about-apis/authentication#api-access-modes). These are used to authenticate requests made by the app to the Shopify API.
 
 By default, the gem generates an embedded app frontend that uses [Shopify App Bridge](https://shopify.dev/tools/app-bridge) to fetch [session tokens](https://shopify.dev/concepts/apps/building-embedded-apps-using-session-tokens). Session tokens are used by the embedded app to make authenticated requests to the app backend. 
 
-See [*Authenticate an embedded app using session tokens*](https://shopify.dev/tutorials/authenticate-your-app-using-session-tokens) to learn more. 
+See [*Getting started with session token authentication*](https://shopify.dev/docs/apps/auth/oauth/session-tokens/getting-started) to learn more. 
 
 > ⚠️ Be sure you understand the differences between the types of authentication schemes before reading this guide.
 
 #### Table of contents
 
-[OAuth callback](#oauth-callback)
+* [Supported types of OAuth Flow](#supported-types-of-oauth)
+  * [Token Exchange](#token-exchange)
+  * [Authorization Code Grant Flow](#authorization-code-grant-flow)
+    * [OAuth callback](#oauth-callback)
+      * [Customizing callback controller](#customizing-callback-controller)
+    * [Detecting scope changes](#detecting-scope-changes-1)
+* [Run jobs after the OAuth flow](#post-authenticate-tasks)
+* [Rotate API credentials](#rotate-api-credentials)
+* [Making authenticated API requests after authorization](#making-authenticated-api-requests-after-authorization)
 
-[Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
+## Supported types of OAuth
+> [!TIP]
+> If you are building an embedded app, we **strongly** recommend using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+with [token exchange](#token-exchange) instead of the authorization code grant flow.
 
-[Rotate API credentials](#rotate-api-credentials)
+1. [Token Exchange](#token-exchange)
+    - Recommended and is only available for embedded apps
+    - Doesn't require redirects, which makes authorization faster and prevents flickering when loading the app
+    - Access scope changes are handled by Shopify when you use [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+2. [Authorization Code Grant Flow](#authorization-code-grant-flow)
+    - Suitable for non-embedded apps
+    - Installations, and access scope changes are managed by the app
 
-[Available authentication mixins](#available-authentication-mixins)
-  * [`ShopifyApp::Authenticated`](#shopifyappauthenticated)
-  * [`ShopifyApp::EnsureAuthenticatedLinks`](#shopifyappensureauthenticatedlinks)
+## Token Exchange
 
-## OAuth callback
+OAuth process by exchanging the current user's [session token (shopify id token)](https://shopify.dev/docs/apps/auth/session-tokens) for an
+[access token](https://shopify.dev/docs/apps/auth/access-token-types/online.md) to make
+authenticated Shopify API queries. This will replace authorization code grant flow completely when your app is configured with [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
 
->️ **Note:** In Shopify App version 8.4.0, we have extracted the callback logic in its own controller. If you are upgrading from a version older than 8.4.0 the callback action and related helper methods were defined in `ShopifyApp::SessionsController` ==> you will have to extend `ShopifyApp::CallbackController` instead and port your logic to the new controller.
+To enable token exchange authorization strategy, you can follow the steps in ["New embedded app authorization strategy"](/README.md#new-embedded-app-authorization-strategy).
+Upon completion of the token exchange to get the access token, [post authenticated tasks](#post-authenticate-tasks) will be run.
 
-Upon completing the OAuth flow, Shopify calls the app at the `callback_path`. If the app needs to do some extra work, it can define and configure the route to a custom callback controller, inheriting from `ShopifyApp::CallbackController` and hook into or override any of the defined helper methods. The default callback controller already provides the following behaviour:
-* Logging into the shop and resetting the session
-* [Installing Webhooks](/docs/shopify_app/webhooks.md)
-* [Setting Scripttags](/docs/shopify_app/script-tags.md)
-* [Run jobs after the OAuth flow](#run-jobs-after-the-oauth-flow)
-* Redirecting to the return address
+Learn more about:
+- [How token exchange works](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange)
+- [Using Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+- [Configuring access scopes through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration)
 
-## Run jobs after the OAuth flow
+#### Handling invalid access tokens
+If the access token used to make an API call is invalid, the token exchange strategy will handle the error and try to retrieve a new access token before retrying 
+the same operation. 
+See ["Re-fetching an access token when API returns Unauthorized"](/docs/shopify_app/sessions.md#re-fetching-an-access-token-when-api-returns-unauthorized) section for more information.
+
+#### Detecting scope changes
+
+##### Shopify managed installation
+If your access scopes are [configured through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration), scope changes will be handled by Shopify automatically.
+Learn more about [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
+Using token exchange will ensure that the access token retrieved will always have the latest access scopes granted by the user.
+
+## Authorization Code Grant Flow
+Authorization code grant flow is the OAuth flow that requires the app to redirect the user 
+to Shopify for installation/authorization of the app to access the shop's data. It is still required for apps that are not embedded.
+
+If your app is not using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) with declared scopes in your `.toml` file, you can change the requested access scopes during OAuth flow 
+by adding the `scope` to your configurations - `ShopifyApp.configuration` & `ShopifyAPI::Context.setup`.
+
+
+```ruby
+# config/initializers/shopify_app.rb
+
+ShopifyApp.configure do |config|
+  ...
+  config.scope = ["read_discounts", "write_products"]
+  ...
+end
+
+ShopifyAPI::Context.setup(
+  ...
+  scope: ShopifyApp.configuration.scope,
+  ...
+)
+```
+
+To perform [authorization code grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant), you app will need to handle
+[begin OAuth](#begin-oauth) and [OAuth callback](#oauth-callback) routes.
+
+### Begin OAuth
+ShopifyApp automatically redirects the user to Shopify to complete OAuth to install the app when the `ShopifyApp.configuration.login_url` is reached.
+Behind the scenes the ShopifyApp gem starts the process by calling `ShopifyAPI::Auth::Oauth.begin_auth` to build the 
+redirect URL with necessary parameters like the OAuth callback URL, scopes requested, type of access token (offline or online) requested, etc.
+The ShopifyApp gem then redirect the merchant to Shopify, to ask for permission to install the app. (See [ShopifyApp::SessionsController.redirect_to_begin_oauth](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/sessions_controller.rb#L76-L96)
+for detailed implementation)
+
+### OAuth callback
+
+Shopify will redirect the merchant back to your app's callback URL once they approve the app installation.
+Upon completing the OAuth flow, Shopify calls the app at `ShopifyApp.configuration.login_callback_url`. (This was provided to Shopify in the OAuth begin URL parameters)
+
+The default callback controller [`ShopifyApp::CallbackController`](../../app/controllers/shopify_app/callback_controller.rb) provides the following behaviour:
+
+1. Logging into the shop and resetting the session
+2. Storing the session to the `SessionRepository`
+3. [Post authenticate tasks](#post-authenticate-tasks)
+4. Redirecting to the return address
+
+#### Customizing callback controller
+If you need to define a custom callback controller to handle your app's use case, you can configure the callback route to your controller.
+
+Example:
+
+1. Create the new custom callback controller
+```ruby
+# web/app/controllers/my_custom_callback_controller.rb
+
+class MyCustomCallbackController
+  def callback
+    # My custom callback logic
+  end
+end
+```
+
+2. Override callback routing to this controller
+
+```ruby
+# web/config/routes.rb
+
+Rails.application.routes.draw do
+  root to: "home#index"
+
+  # Overriding the callback controller to the new custom one.
+  # This must be added before mounting the ShopifyApp::Engine
+  get ShopifyApp.configuration.login_callback_url, to: 'my_custom_callback#callback'
+
+  mount ShopifyApp::Engine, at: "/api"
+
+  # other routes
+end
+```
+
+### Detecting scope changes
+When the OAuth process is completed, the created session has a `scope` field which holds all of the access scopes that were requested from the merchant at the time.
+
+When an app's access scopes change, it needs to request merchants to go through OAuth again to renew its permissions.
+
+See [Handling changes in access scopes](/docs/shopify_app/handling-access-scopes-changes.md).
+
+## Post Authenticate tasks
+After authentication is complete, a few tasks are run by default by PostAuthenticateTasks:
+1. [Installing Webhooks](/docs/shopify_app/webhooks.md)
+2. [Run configured after_authenticate_job](#after_authenticate_job)
+
+The [PostAuthenticateTasks](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/auth/post_authenticate_tasks.rb)
+class is responsible for triggering the webhooks manager for webhooks registration, and enqueue jobs from [after_authenticate_job](#after_authenticate_job).
+
+If you simply need to enqueue more jobs to run after authenticate, use [after_authenticate_job](#after_authenticate_job) to define these jobs.
+
+If your post authentication tasks is more complex and is different than just installing webhooks and enqueuing jobs,
+you can customize the post authenticate tasks by creating a new class that has a `self.perform(session)` method,
+and configuring `custom_post_authenticate_tasks` in the initializer.
+
+```ruby
+# my_custom_post_authenticate_task.rb
+class MyCustomPostAuthenticateTask
+  def self.perform(session)
+    # This will be triggered after OAuth callback and token exchange completion
+  end
+end
+
+# config/initializers/shopify_app.rb
+ShopifyApp.configure do |config|
+  config.custom_post_authenticate_tasks = "MyCustomPostAuthenticateTask"
+end
+```
+
+#### after_authenticate_job
 
 See [`ShopifyApp::AfterAuthenticateJob`](/lib/generators/shopify_app/add_after_authenticate_job/templates/after_authenticate_job.rb).
 
-If your app needs to perform specific actions after the user is authenticated successfully (i.e. every time a new session is created), ShopifyApp can queue or run a job of your choosing (note that we already provide support for automatically creating Webhooks and Scripttags). To configure the after authenticate job, update your initializer as follows:
+If your app needs to perform specific actions after the user is authenticated successfully (i.e. every time a new session is created), ShopifyApp can queue or run a job of your choosing. To configure the after authenticate job, update your initializer as follows:
 
 ```ruby
 ShopifyApp.configure do |config|
@@ -49,7 +192,7 @@ If you need the job to run synchronously add the `inline` flag:
 
 ```ruby
 ShopifyApp.configure do |config|
-  config.after_authenticate_job = { job: Shopify::AfterAuthenticateJob, inline: true }
+  config.after_authenticate_job = { job: "Shopify::AfterAuthenticateJob", inline: true }
 end
 ```
 
@@ -63,7 +206,7 @@ If you want to perform that action only once, e.g. send a welcome email to the u
 
 ## Rotate API credentials
 
-If your Shopify secret key is leaked, you can use the RotateShopifyTokenJob to perform [API Credential Rotation](https://help.shopify.com/en/api/getting-started/authentication/oauth/api-credential-rotation).
+If your Shopify secret key is leaked, you can use the `RotateShopifyTokenJob` to perform [API Credential Rotation](https://help.shopify.com/en/api/getting-started/authentication/oauth/api-credential-rotation).
 
 Before running the job, you'll need to generate a new secret key from your Shopify Partner dashboard, and update the `/config/initializers/shopify_app.rb` to hold your new and old secret keys:
 
@@ -72,6 +215,17 @@ config.secret = Rails.application.secrets.shopify_secret
 config.old_secret = Rails.application.secrets.old_shopify_secret
 ```
 
+Also make sure the old secret is specified when setting up `ShopifyAPI::Context` as well:
+
+```ruby
+ShopifyAPI::Context.setup(
+  api_key: ShopifyApp.configuration.api_key,
+  api_secret_key: ShopifyApp.configuration.secret,
+  # ...
+  old_api_secret_key: ShopifyApp.configuration.old_secret,
+)
+```
+
 We've provided a generator which creates the job and an example rake task:
 
 ```sh
@@ -86,43 +240,10 @@ strategy.options[:old_client_secret] = ShopifyApp.configuration.old_secret
 
 > **Note:** If you are updating `shopify_app` from a version prior to 8.4.2 (and do not wish to run the default/install generator again), you will need to add [the following line](https://github.com/Shopify/shopify_app/blob/4f7e6cca2a472d8f7af44b938bd0fcafe4d8e88a/lib/generators/shopify_app/install/templates/shopify_provider.rb#L18) to `config/initializers/omniauth.rb`:
 
-## Available authentication mixins
+## Making authenticated API requests after authorization
+After the app is installed onto a shop and has been granted all necessary permission, a new session record will be added to `SessionRepository#shop_storage`, or `SessionRepository#user_storage` if online sessions are enabled.
 
-### `ShopifyApp::Authenticated`
-
-The engine provides a [`ShopifyApp::Authenticated`](/app/controllers/concerns/shopify_app/authenticated.rb) concern which should be included in any controller that is intended to be behind Shopify OAuth. It adds `before_action`s to ensure that the user is authenticated and will redirect to the Shopify login page if not. It is best practice to include this concern in a base controller inheriting from your `ApplicationController`, from which all controllers that require Shopify authentication inherit.
-
-*Example:*
-
-```rb
-class AuthenticatedController < ApplicationController
-  include ShopifyApp::Authenticated
-end
-
-class ApiController < AuthenticatedController
-  # Actions in this controller are protected
-end
-```
-
-For backwards compatibility, the engine still provides a controller called `ShopifyApp::AuthenticatedController` which includes the `ShopifyApp::Authenticated` concern. Note that it inherits directly from `ActionController::Base`, so you will not be able to share functionality between it and your application's `ApplicationController`.
-
-#### Embedded apps and `ShopifyApp::Authenticated`
-
-Embedded Shopify Admin apps can only use the `ShopifyApp::Authenticated` controller concern *if* the requests originate from App Bridge's `authenticatedFetch` method. Those who include this concern in the `HomeController` or some other embedded controller will see what looks like an OAuth redirect loop as the `ShopifyApp::Authenticated` concern will be fighting with the App Bridge. For more details on how to handle embedded sessions, refer to [the session token documentation](https://shopify.dev/apps/auth/oauth/session-tokens).
-
-### `ShopifyApp::EnsureAuthenticatedLinks`
-
-The [`ShopifyApp::EnsureAuthenticatedLinks`](/app/controllers/concerns/shopify_app/ensure_authenticated_links.rb) concern helps authenticate users that access protected pages of your app directly.
-
-Include this concern in your app's `AuthenticatedController` if your app uses session tokens with [Turbolinks](https://github.com/turbolinks/turbolinks). It adds a `before_action` filter that detects whether a session token is present or not. If a session token is not found, the user is redirected to your app's splash page path (`root_path`) along with `return_to` and `shop` parameters.
-
-*Example:*
-
-```rb
-class AuthenticatedController < ApplicationController
-  include ShopifyApp::EnsureAuthenticatedLinks
-  include ShopifyApp::Authenticated
-end
-```
+When your app needs to make API requests to Shopify, `ShopifyApp`'s `ActiveSupport` controller concerns can help you retrieve the active session token from the repository to make the authenticate API call.
 
-See [Authenticate server-side rendered embedded apps using Rails and Turbolinks](https://shopify.dev/tutorials/authenticate-server-side-rendered-embedded-apps-using-rails-and-turbolinks) for more information.
+- ⚠️ See [Sessions](./sessions.md) page to understand how sessions work.
+- ⚠️ See [Controller Concerns](./controller-concerns.md) page to understand when to use which concern.