Token exchange docs

.changeset/lucky-cooks-glow.md

@@ -0,0 +1,2 @@
+---
+---

packages/shopify-app-remix/CHANGELOG.md

@@ -6,6 +6,8 @@
 
 - 2473c85: Add new embedded authorization strategy relying on Shopify managed install and OAuth token exchange
 
+  :exclamation: For more information on how to enable this feature, see ["New Embedded Authorization Strategy"](./README.md#new-embedded-authorization-strategy)
+
 ### Patch Changes
 
 - 35b74dd: Fixes a bug that was causing external redirects to fail in remix actions

packages/shopify-app-remix/README.md

@@ -174,6 +174,50 @@ Here are some guides to help you set up your app:
 You can also authenticate requests from surfaces other than the admin.
 To see all supported methods, see [the `shopify.authenticate` object documentation](https://shopify.dev/docs/api/shopify-app-remix/latest/authenticate).
 
+### New embedded app authorization strategy
+
+> [!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](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) instead of the legacy authorization code grant flow.
+
+We've introduced a new installation and authorization strategy for **embedded apps** that
+eliminates the redirects that were previously necessary.
+It replaces the existing [installation and authorization code grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant).
+
+This is achieved by using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+to handle automatic app installations and scope updates, while utilizing
+[token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) to retrieve an access token for
+authenticated API access.
+
+##### Enabling this new strategy in your app
+
+> [!NOTE]
+> Newly created Remix apps from the template after February 1st 2024 has this feature enabled by default.
+
+1. Enable [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)
+   by configuring your scopes [through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration).
+2. Enable the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file.
+
+```ts
+// my-app/app/shopify.server.ts
+const shopify = shopifyApp({
+  ...
+  isEmbeddedApp: true,
+  future: {
+    unstable_newEmbeddedAuthStrategy: true,
+  }
+})
+
+```
+
+3. Enjoy a smoother and faster app installation process.
+
+###### 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)
+
 ## Gotchas / Troubleshooting
 
 If you're experiencing unexpected behaviors when using this package, check our [app template's documentation](https://github.com/Shopify/shopify-app-template-remix#gotchas--troubleshooting) for the solution to common issues.

packages/shopify-app-remix/docs/generated/generated_static_pages.json

@@ -163,6 +163,12 @@
             "value": "",
             "description": "Returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.\n\nSee [authenticate.webhook](/docs/api/shopify-app-remix/authenticate/webhook#example-admin) for more details.",
             "isOptional": true
+          },
+          {
+            "name": "unstable_newEmbeddedAuthStrategy",
+            "value": "",
+            "description": "Embedded apps will fetch access tokens via token exchange. This assumes the app has declared scopes for Shopify managed installations.\n\nLearn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).",
+            "isOptional": true
           }
         ]
       }
@@ -416,7 +422,7 @@
         "type": "Generic",
         "anchorLink": "auth-route",
         "title": "OAuth route",
-        "sectionContent": "To install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`.\n\nWhen that function is called, the package will start the OAuth process, and handle the callback from Shopify after it completes.\n\nThe default route is `/app/routes/auth/$.tsx`, but you can configure this route using the `authPathPrefix` option.",
+        "sectionContent": "> Tip: This is only applicable to non-embedded apps or legacy embedded apps that are **not** using the [new embedded app authorization strategy](#embedded-auth-strategy) for OAuth and installation flow. If you're building an embedded app, we **strongly** recommend using the [new embedded app authorization strategy](#embedded-auth-strategy)\n\nTo install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`.\n\nWhen that function is called, the package will start the OAuth process, and handle the callback from Shopify after it completes.\n\nThe default route is `/app/routes/auth/$.tsx`, but you can configure this route using the `authPathPrefix` option.",
         "codeblock": {
           "title": "Add OAuth route",
           "tabs": [
@@ -428,6 +434,22 @@
           ]
         }
       },
+      {
+        "type": "Generic",
+        "anchorLink": "embedded-auth-strategy",
+        "title": "New embedded app authorization strategy",
+        "sectionContent": "> Tip: This is available for embedded apps that are using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).\n> If you're building an embedded app, we **strongly** recommend using this feature that utilizes Shopify managed install with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange).\n\n We have introduced a new authorization and installation strategy for **embedded apps** that eliminates the redirects that were previously necessary. It replaces the legacy [authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant).\n\nIt takes advantage of [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) to handle automatic app installations and scope updates, while using [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) to get an access token for the logged-in user.\n\n > Note: Newly created Remix apps from the template after February 1st 2024 has this feature enabled by default.\n\n1. Enable [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation) by configuring your scopes [through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration).\n2. Enable the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file.\n3. Enjoy no-redirect OAuth flow, and app installation process.",
+        "codeblock": {
+          "title": "Enabling the new embedded auth strategy",
+          "tabs": [
+            {
+              "title": "/app/shopify.server.ts",
+              "language": "ts",
+              "code": "// ... imports\nconst shopify = shopifyApp({\n  // .. and the rest of the config\n  isEmbeddedApp: true,\n  future: {\n    unstable_newEmbeddedAuthStrategy: true,\n  },\n)};\n\n// ... exports\n"
+            }
+          ]
+        }
+      },
       {
         "type": "Generic",
         "anchorLink": "app-provider",
@@ -515,4 +537,4 @@
       }
     ]
   }
-]
+]

packages/shopify-app-remix/docs/staticPages/examples/index/embedded-app-auth-strategy-config.example.ts

@@ -0,0 +1,10 @@
+// ... imports
+const shopify = shopifyApp({
+  // .. and the rest of the config
+  isEmbeddedApp: true,
+  future: {
+    unstable_newEmbeddedAuthStrategy: true,
+  },
+)};
+
+// ... exports

packages/shopify-app-remix/docs/staticPages/future-flags.doc.ts

@@ -70,6 +70,14 @@ const data: LandingTemplateSchema = {
             '\n\nSee [authenticate.webhook](/docs/api/shopify-app-remix/authenticate/webhook#example-admin) for more details.',
           isOptional: true,
         },
+        {
+          name: 'unstable_newEmbeddedAuthStrategy',
+          value: '',
+          description:
+            'Embedded apps will fetch access tokens via token exchange. This assumes the app has declared scopes for Shopify managed installations.' +
+            '\n\nLearn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).',
+          isOptional: true,
+        },
       ],
     },
   ],

packages/shopify-app-remix/docs/staticPages/index.doc.ts

@@ -138,7 +138,9 @@ const data: LandingTemplateSchema = {
       anchorLink: 'auth-route',
       title: 'OAuth route',
       sectionContent:
-        "To install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`." +
+        "> Tip: This is only applicable to non-embedded apps or legacy embedded apps that are **not** using the [new embedded app authorization strategy](#embedded-auth-strategy) for OAuth and installation flow. If you're building an embedded app, we **strongly** recommend using the" +
+        " [new embedded app authorization strategy](#embedded-auth-strategy)" +
+        "\n\nTo install an app or refresh tokens, you'll need to set up an [OAuth](docs/apps/auth/oauth) route. To do that, set up a [splat route](https://remix.run/docs/en/main/guides/routing#splats) that calls `authenticate.admin`." +
         '\n\nWhen that function is called, the package will start the OAuth process, and handle the callback from Shopify after it completes.' +
         '\n\nThe default route is `/app/routes/auth/$.tsx`, but you can configure this route using the `authPathPrefix` option.',
       codeblock: {
@@ -152,6 +154,35 @@ const data: LandingTemplateSchema = {
         ],
       },
     },
+    {
+      type: 'Generic',
+      anchorLink: 'embedded-auth-strategy',
+      title: 'New embedded app authorization strategy',
+      sectionContent:
+        "> Tip: This is available for embedded apps that are using [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)." +
+        "\n> If you're building an embedded app, we **strongly** recommend using this feature that utilizes Shopify managed install with [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange)." +
+        "\n\n We have introduced a new authorization and installation strategy for **embedded apps** that eliminates the redirects that were previously necessary." +
+        " It replaces the legacy [authorization Code install and grant flow](https://shopify.dev/docs/apps/auth/get-access-tokens/authorization-code-grant)." +
+        "\n\nIt takes advantage of [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)" +
+        " to handle automatic app installations and scope updates, while using" +
+        " [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange) to get an access token for the logged-in user." +
+        "\n\n > Note: Newly created Remix apps from the template after February 1st 2024 has this feature enabled by default." +
+        "\n\n1. Enable [Shopify managed installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation)" +
+        " by configuring your scopes [through the Shopify CLI](https://shopify.dev/docs/apps/tools/cli/configuration)." +
+        "\n2. Enable the future flag `unstable_newEmbeddedAuthStrategy` in your app's server configuration file." +
+        "\n3. Enjoy no-redirect OAuth flow, and app installation process.",
+      codeblock: {
+        title: 'Enabling the new embedded auth strategy',
+        tabs: [
+          {
+            title: '/app/shopify.server.ts',
+            language: 'ts',
+            code: './examples/index/embedded-app-auth-strategy-config.example.ts',
+
+          }
+        ],
+      }
+    },
     {
       type: 'Generic',
       anchorLink: 'app-provider',

packages/shopify-app-remix/src/server/future/flags.ts

@@ -16,7 +16,10 @@ export interface FutureFlags {
   v3_authenticatePublic?: boolean;
 
   /**
-   * When enabled, embedded apps will fetch access tokens via token exchange. This assumes app are using declarative scopes with Shopify managing installs.
+   * When enabled, embedded apps will fetch access tokens via [token exchange](https://shopify.dev/docs/apps/auth/get-access-tokens/token-exchange).
+   * This assumes the app has scopes declared for [Shopify managing installation](https://shopify.dev/docs/apps/auth/installation#shopify-managed-installation).
+   *
+   * Learn more about this [new embedded app auth strategy](https://shopify.dev/docs/api/shopify-app-remix#embedded-auth-strategy).
    *
    * @default false
    */

packages/shopify-app-remix/src/server/shopify-app.doc.ts

@@ -20,6 +20,7 @@ const data: ReferenceEntityTemplateSchema = {
         'Set future flags using the `future` configuration field to opt in to upcoming breaking changes.' +
         '\n\nWith this feature, you can prepare for major releases ahead of time, as well as try out new features before they are released.',
       type: 'FutureFlags',
+      filePath: 'src/server/future/flags.ts',
     },
   ],
   jsDocTypeExamples: [