Merge pull request #2960 from Shopify/06-06-added_docs_on_session_tokens_and_app_permissions

Added docs on session tokens and app permissions

Author: js-goupil

packages/ui-extensions/docs/surfaces/point-of-sale/staticPages/pages/pos-overview.doc.ts

@@ -83,7 +83,7 @@ const data: LandingTemplateSchema = {
         },
       ],
       sectionContent:
-        "POS UI extensions can also make authenticated calls to your app's backend. When you use `fetch()` to make a request to your app's configured auth domain or any of its subdomains, an `Authorization` header is automatically added with a Shopify [OpenID Connect ID Token (formerly known as a Session Token)](https://shopify.dev/docs/api/app-bridge-library/reference/id-token). There's no need to manually manage ID tokens.\n\nRelative URLs passed to `fetch()` are resolved against your app's `app_url`. This means if your app's backend is on the same domain as your `app_url`, you can make requests to it using `fetch('/path')`.\n\nIf you need to make requests to a different domain, you can use the [`session.getSessionToken()` method](/docs/api/pos-ui-extensions/apis/session-api#sessionapi-propertydetail-getsessiontoken) to retrieve the ID token and manually add it to your request headers.",
+        "POS UI extensions can also make authenticated calls to your app's backend. When you use `fetch()` to make a request to your app's configured auth domain or any of its subdomains, an `Authorization` header is automatically added with a Shopify [OpenID Connect ID Token (formerly known as a Session Token)](/docs/api/app-bridge-library/reference/id-token). There's no need to manually manage ID tokens.\n\nRelative URLs passed to `fetch()` are resolved against your app's `app_url`. This means if your app's backend is on the same domain as your `app_url`, you can make requests to it using `fetch('/path')`.\n\nIf you need to make requests to a different domain, you can use the [`session.getSessionToken()` method](/docs/api/pos-ui-extensions/apis/session-api#sessionapi-propertydetail-getsessiontoken) to retrieve the ID token and manually add it to your request headers.\n\n**Important**: ID tokens are only returned for authenticated users who are permitted to use your app. When the authenticated user (the user that logged into Shopify POS with their email address) doesn't have the correct app permission enabled for your app, the token will be null. This is irrelevant of which POS Staff member is pinned in, as those are not authenticated users. For more information on configuring app permissions, see the [Shopify app permissions documentation](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).",
       anchorLink: 'app-authentication',
       codeblock: {
         title: "Make requests to your app's backend",

packages/ui-extensions/docs/surfaces/point-of-sale/staticPages/pages/troubleshooting.doc.ts

@@ -99,6 +99,24 @@ This error is most likely from missing a dependency in package.json in the app r
 
 This issue commonly happens when \`Yarn\` is used for dependency management. The package's version was updated but \`npm\` conflicts with \`Yarn\`. In the root of your application run \`npm install\` to get it up to date as well. Restart your IDE if necessary.`,
     },
+    {
+      type: 'Generic',
+      anchorLink: 'session-token-null',
+      title: 'Session tokens are being returned as null',
+      sectionContent: `
+### Resolution
+
+The \`getSessionToken()\` function returns \`null\` when the authenticated user (the user that logged into Shopify POS with their email address) doesn't have the correct app permissions enabled for your app. Session tokens are only returned for authenticated users who have enabled the correct app permission for the app making the request. This is irrelevant of POS Staff members, as those are not authenticated users. 
+
+To resolve this issue:
+
+1. **Check app permissions**: Verify that the authenticated user has the correct app permission enabled for your app. This can be seen in the Shopify Admin by navigating to Settings > Users > Select a user > Scroll down to view the permissions summary.
+
+2. **Enable app permissions**: If the user does not have permissions to use your app, it can be added to one of the roles that is assigned to that user. This can be done in the Shopify Admin by navigating to Settings > Users > Roles > Select a role. You can then scroll down to the apps section and select the app for which you want to grant the user permissions.
+
+For more information on configuring and managing app permissions, see the [Shopify app permissions documentation](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).
+      `,
+    },
   ],
 };
 

packages/ui-extensions/src/surfaces/point-of-sale/render/api/session-api/session-api.ts

@@ -7,6 +7,8 @@ export interface SessionApiContent {
   currentSession: Session;
   /**
    * Get a fresh session token for communication with your app's backend service.
+   * When the authenticated user (the user that logged into Shopify POS with their email address) doesn't have the correct app permissions enabled for your app, null will be returned. This is irrelevant of which POS Staff member is pinned in, as those are not authenticated users.
+   * For more information, see our [app permissions documentation](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).
    * Calls to Shopify APIs must be made by your app’s backend service.
    */
   getSessionToken: () => Promise<string | undefined>;