Session Token

The API for interacting with session tokens.

Using a session token with fetch()

import {useEffect} from 'react';
import {
  reactExtension,
  Banner,
  useApi,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  const {sessionToken} = useApi();

  useEffect(() => {
    async function queryApi() {
      // Request a new (or cached) session token from Shopify
      const token = await sessionToken.get();
      console.log('sessionToken.get()', token);

      const apiResponse =
        await fetchWithToken(token);
      // Use your response
      console.log('API response', apiResponse);
    }

    function fetchWithToken(token) {
      const result = fetch(
        'https://myapp.com/api/session-token',
        {
          headers: {
            Authorization: `Bearer ${token}`,
          },
        },
      );
      return result;
    }

    queryApi();
  }, [sessionToken]);

  return (
    <Banner>See console for API response</Banner>
  );
}

import {
  extension,
  Banner,
  BlockStack,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, {sessionToken}) => {
    async function queryApi() {
      // Request a new (or cached) session token from Shopify
      const token = await sessionToken.get();
      console.log(token);

      const apiResponse =
        await fetchWithToken(token);

      // Use your response
      console.log(apiResponse);
    }

    function fetchWithToken(token) {
      const result = fetch(
        'https://myapp.com/api/session-token',
        {
          headers: {
            Authorization: `Bearer ${token}`,
          },
        },
      );

      return result;
    }

    queryApi();

    root.appendChild(
      root.createComponent(Banner, {
        title: 'Session Token Extension',
      }),
    );
  },
);

StandardApi

The base API object provided to this and other `customer-account` extension targets.

Docs_Standard_SessionTokenApi

sessionToken

Provides access to session tokens, which can be used to verify token claims on your app's server. See [session token examples](/docs/api/customer-account-ui-extensions/apis/session-token#examples) for more information.

SessionToken

get

Requests a session token that hasn't expired. You should call this method every time you need to make a request to your backend in order to get a valid token. This method will return cached tokens when possible, so you don’t need to worry about storing these tokens yourself.

useSessionToken

Returns a the session token API object.

UseSessionTokenGeneratedType

Provides access to session tokens, which can be used to verify token claims on your app's server.

Returns: SessionToken

export function useSessionToken< Target extends RenderExtensionTarget = RenderExtensionTarget, >(): SessionToken { const api = useApi<Target>(); const extensionTarget = api.extension.target; if (!('sessionToken' in api)) { throw new ExtensionHasNoFieldError('sessionToken', extensionTarget); } return api.sessionToken; }

SessionToken

get

Requests a session token that hasn't expired. You should call this method every time you need to make a request to your backend in order to get a valid token. This method will return cached tokens when possible, so you don’t need to worry about storing these tokens yourself.

Examples

The API for interacting with session tokens.

The contents of the token are signed using your shared app secret. The optional `sub` claim contains the customer's `gid` if they are logged in and your app has permission to read customer accounts. For example, a loyalty app that needs to check a customer's point balance can use the `sub` claim to verify the customer's account.

Session token claims

{
  // Shopify URL
  "dest": "store-name.myshopify.com",
  // The Client ID of your app
  "aud": "<clientId>",
  // When the token expires.  Set at 5 minutes.
  "exp": 1679954053,
  // When the token was actived
  "nbf": 1679953753,
  // When the token was issued
  "iat": 1679953753,
  // A unique identifier (a nonce) to prevent replay attacks
  "jti": "6c992878-dbaf-48d1-bb9d-6d9b59814fd1",
  // Optional claim present when a customer is logged in and your app has permissions to read customer data
  "sub": "gid://shopify/Customer/<customerId>"
}

Session token claims

{
  // Shopify URL
  "dest": "store-name.myshopify.com",
  // The Client ID of your app
  "aud": "<clientId>",
  // When the token expires.  Set at 5 minutes.
  "exp": 1679954053,
  // When the token was actived
  "nbf": 1679953753,
  // When the token was issued
  "iat": 1679953753,
  // A unique identifier (a nonce) to prevent replay attacks
  "jti": "6c992878-dbaf-48d1-bb9d-6d9b59814fd1",
  // Optional claim present when a customer is logged in and your app has permissions to read customer data
  "sub": "gid://shopify/Customer/<customerId>"
}