Add API for migrating non expiring to expiring offline tokens

Author: zzooeeyy

CHANGELOG.md

@@ -4,6 +4,7 @@ Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 ## Unreleased
 
 - Add support for expiring offline access tokens with refresh tokens. See [OAuth documentation](docs/usage/oauth.md#expiring-offline-access-tokens) for details.
+- Add `ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token` method to migrate existing non-expiring offline tokens to expiring tokens. See [migration documentation](docs/usage/oauth.md#migrating-non-expiring-tokens-to-expiring-tokens) for details.
 
 ### 15.0.0
 

docs/usage/oauth.md

@@ -16,6 +16,7 @@ For more information on authenticating a Shopify app please see the [Types of Au
 - [Expiring Offline Access Tokens](#expiring-offline-access-tokens)
   - [Enabling Expiring Offline Access Tokens](#enabling-expiring-offline-access-tokens)
   - [Refreshing Access Tokens](#refreshing-access-tokens)
+  - [Migrating Non-Expiring Tokens to Expiring Tokens](#migrating-non-expiring-tokens-to-expiring-tokens)
 - [Using OAuth Session to make authenticated API calls](#using-oauth-session-to-make-authenticated-api-calls)
 
 ## Session Persistence
@@ -387,6 +388,51 @@ if session.refresh_token_expired?
 end
 ```
 
+### Migrating Non-Expiring Tokens to Expiring Tokens
+
+If you have existing non-expiring offline access tokens and want to migrate them to expiring tokens, you can use the `ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token` method. This performs a token exchange that converts your non-expiring offline token into an expiring one with a refresh token.
+
+> [!WARNING]
+> This is a **one-time, irreversible migration** per shop. Once you migrate a shop's token to an expiring token, you cannot convert it back to a non-expiring token. The shop would need to reinstall your app with `expiring_offline_access_tokens: false` in your Context configuration to obtain a new non-expiring token.
+
+#### Input
+| Parameter      | Type     | Required? | Notes                                                                                           |
+| -------------- | -------- | :-------: | ----------------------------------------------------------------------------------------------- |
+| `non_expiring_offline_session` | `ShopifyAPI::Auth::Session` | Yes | A Session object containing the non-expiring offline access token to migrate. |
+
+#### Output
+This method returns a new `ShopifyAPI::Auth::Session` object with an expiring access token and refresh token. Your app should store this new session to replace the non-expiring one.
+
+#### Example
+```ruby
+def migrate_shop_to_expiring_offline_token(shop)
+  # Retrieve the existing non-expiring session
+  old_session = MyApp::SessionRepository.retrieve_shop_session_by_shopify_domain(shop)
+
+  # Migrate to expiring token
+  new_session = ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token(
+    non_expiring_offline_session: old_session
+  )
+
+  # Store the new expiring session, replacing the old one
+  MyApp::SessionRepository.store_shop_session(new_session)
+end
+```
+
+#### Migration Strategy
+When migrating your app to use expiring tokens, follow this order:
+
+1. **Update your database schema** to add `expires_at` (timestamp), `refresh_token` (string) and `refresh_token_expires` (timestamp) columns to your session storage
+2. **Implement refresh logic** in your app to handle token expiration using `ShopifyAPI::Auth::RefreshToken.refresh_access_token`
+3. **Enable expiring tokens in your Context setup** so new installations will request and receive expiring tokens:
+   ```ruby
+   ShopifyAPI::Context.setup(
+     expiring_offline_access_tokens: true,
+     # ... other config
+   )
+   ```
+4. **Migrate existing non-expiring tokens** for shops that have already installed your app using the migration method above
+
 ## Using OAuth Session to make authenticated API calls
 Once your OAuth flow is complete, and you have persisted your `Session` object, you may use that `Session` object to make authenticated API calls.
 

lib/shopify_api/auth/token_exchange.rb

@@ -78,6 +78,50 @@ def exchange_token(shop:, session_token:, requested_token_type:)
             access_token_response: Oauth::AccessTokenResponse.from_hash(session_params),
           )
         end
+
+        sig do
+          params(
+            non_expiring_offline_session: ShopifyAPI::Auth::Session,
+          ).returns(ShopifyAPI::Auth::Session)
+        end
+        def migrate_to_expiring_token(non_expiring_offline_session:)
+          unless ShopifyAPI::Context.setup?
+            raise ShopifyAPI::Errors::ContextNotSetupError,
+              "ShopifyAPI::Context not setup, please call ShopifyAPI::Context.setup"
+          end
+
+          body = {
+            client_id: ShopifyAPI::Context.api_key,
+            client_secret: ShopifyAPI::Context.api_secret_key,
+            grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+            subject_token: non_expiring_offline_session.access_token,
+            subject_token_type: RequestedTokenType::OFFLINE_ACCESS_TOKEN.serialize,
+            requested_token_type: RequestedTokenType::OFFLINE_ACCESS_TOKEN.serialize,
+            expiring: "1",
+          }
+
+          client = Clients::HttpClient.new(session: non_expiring_offline_session, base_path: "/admin/oauth")
+          response = begin
+            client.request(
+              Clients::HttpRequest.new(
+                http_method: :post,
+                path: "access_token",
+                body: body,
+                body_type: "application/json",
+              ),
+            )
+          rescue ShopifyAPI::Errors::HttpResponseError => error
+            ShopifyAPI::Context.logger.debug("Failed to migrate to expiring offline token: #{error.message}")
+            raise error
+          end
+
+          session_params = T.cast(response.body, T::Hash[String, T.untyped]).to_h
+
+          Session.from(
+            shop: non_expiring_offline_session.shop,
+            access_token_response: Oauth::AccessTokenResponse.from_hash(session_params),
+          )
+        end
       end
     end
   end

test/auth/token_exchange_test.rb

@@ -228,6 +228,98 @@ def test_exchange_token_online_token
 
         assert_equal(expected_session, session)
       end
+
+      def test_migrate_to_expiring_token_context_not_setup
+        modify_context(api_key: "", api_secret_key: "", host: "")
+        non_expiring_session = ShopifyAPI::Auth::Session.new(
+          shop: @shop,
+          access_token: "old-offline-token-123",
+        )
+
+        assert_raises(ShopifyAPI::Errors::ContextNotSetupError) do
+          ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token(
+            non_expiring_offline_session: non_expiring_session,
+          )
+        end
+      end
+
+      def test_migrate_to_expiring_token_success
+        non_expiring_token = "old-offline-token-123"
+        non_expiring_session = ShopifyAPI::Auth::Session.new(
+          shop: @shop,
+          access_token: non_expiring_token,
+        )
+        migration_request = {
+          client_id: ShopifyAPI::Context.api_key,
+          client_secret: ShopifyAPI::Context.api_secret_key,
+          grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+          subject_token: non_expiring_token,
+          subject_token_type: "urn:shopify:params:oauth:token-type:offline-access-token",
+          requested_token_type: "urn:shopify:params:oauth:token-type:offline-access-token",
+          expiring: "1",
+        }
+
+        stub_request(:post, "https://#{@shop}/admin/oauth/access_token")
+          .with(
+            body: migration_request,
+            headers: { "Content-Type" => "application/json" },
+          )
+          .to_return(body: @expiring_offline_token_response.to_json, headers: { content_type: "application/json" })
+
+        expected_session = ShopifyAPI::Auth::Session.new(
+          id: "offline_#{@shop}",
+          shop: @shop,
+          access_token: @expiring_offline_token_response[:access_token],
+          scope: @expiring_offline_token_response[:scope],
+          is_online: false,
+          expires: @stubbed_time_now + @expiring_offline_token_response[:expires_in].to_i,
+          shopify_session_id: @expiring_offline_token_response[:session],
+          refresh_token: @expiring_offline_token_response[:refresh_token],
+          refresh_token_expires: @stubbed_time_now + @expiring_offline_token_response[:refresh_token_expires_in].to_i,
+        )
+
+        session = Time.stub(:now, @stubbed_time_now) do
+          ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token(
+            non_expiring_offline_session: non_expiring_session,
+          )
+        end
+
+        assert_equal(expected_session, session)
+      end
+
+      def test_migrate_to_expiring_token_http_error
+        non_expiring_token = "old-offline-token-123"
+        non_expiring_session = ShopifyAPI::Auth::Session.new(
+          shop: @shop,
+          access_token: non_expiring_token,
+        )
+        migration_request = {
+          client_id: ShopifyAPI::Context.api_key,
+          client_secret: ShopifyAPI::Context.api_secret_key,
+          grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+          subject_token: non_expiring_token,
+          subject_token_type: "urn:shopify:params:oauth:token-type:offline-access-token",
+          requested_token_type: "urn:shopify:params:oauth:token-type:offline-access-token",
+          expiring: "1",
+        }
+
+        stub_request(:post, "https://#{@shop}/admin/oauth/access_token")
+          .with(
+            body: migration_request,
+            headers: { "Content-Type" => "application/json" },
+          )
+          .to_return(
+            status: 400,
+            body: { error: "invalid_subject_token" }.to_json,
+            headers: { content_type: "application/json" },
+          )
+
+        assert_raises(ShopifyAPI::Errors::HttpResponseError) do
+          ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token(
+            non_expiring_offline_session: non_expiring_session,
+          )
+        end
+      end
     end
   end
 end