> Deprecated:
> Product subscription app extensions won't be supported as of December 3, 2025. You should migrate existing product subscription app extensions to [purchase options extensions](/docs/apps/build/purchase-options/purchase-options-extensions).


App Bridge Admin apps use session tokens to authenticate requests between the extension and your app's backend server. Session tokens are secure packets of data about a merchant session in the Shopify Admin, similar to cookies. A session token provides the information required to validate that a request is coming from Shopify, and also provides the IDs of the user and shop. Learn more about [session tokens](/docs/apps/build/authentication-authorization/session-tokens).

This tutorial describes how to authenticate requests between your extension and your app's backend server using session tokens.

## What you'll learn

In this tutorial, you'll learn how to do the following tasks:

- Make a request to your app's server using a session token
- Receive a request and decode the session token
- Validate a session token

## Requirements

- Complete the [Getting started tutorial](/docs/apps/build/purchase-options/product-subscription-app-extensions).
- Familiarize yourself with [data and UI component rendering and extension points](/docs/apps/build/purchase-options/product-subscription-app-extensions/extension-points).

## Step 1: Make requests to your app’s server using a session token

When an extension built with App Bridge Admin loads in the Shopify Admin, you can fetch the session token using the session token API. Include the token with every request that you make to your app's backend server. The token is signed using a shared secret so that your app's backend can verify if the request is valid.

### Configure your app's backend server

Extensions built using App Bridge Admin are hosted on Shopify's servers. To receive requests from your extension, you need to enable cross-domain requests on your app's backend server.

If you're using Rails, then add the following code in the `config/application.rb` file to enable cross-domain requests:

```ruby
Rails.application.config.middleware.insert_before(0, Rack::Cors) do
  allow do
    origins '*' # Allow access to this api from any domain
    resource '*', # Allow all origins access to all resources
      headers: ['authorization', 'content-type', 'context'], # Restrict headers to relevant keys
      methods: [:post] # Restrict the methods to only the ones expected to be used by the extension
  end
end
```


### Fetch a session token from the Shopify Admin

In your extension, use the session token API to fetch a new session token. Session tokens expire every minute, so always fetch a new token before making a request to your app's backend server.


```typescript?title: 'JavaScript'
import {extend, TextField} from '@shopify/admin-ui-extensions';

function MyExtension(root, api) {
  const sessionToken = api.sessionToken;

  const text = root.createComponent(TextField, {
    disabled: true,
    value: '',
    label: 'Session Token',
  });

  sessionToken.getSessionToken().then((newToken) => {
    text.updateProps({
      value: newToken,
    });
  });

  root.appendChild(text);
  root.mount();
}

extend('MyExtensionPoint', MyExtension);
```

```typescript?title: 'React'

import {TextField} from '@shopify/admin-ui-extensions';
import {extend, render, useSessionToken} from '@shopify/admin-ui-extensions-react';

function App() {
  const {getSessionToken} = useSessionToken();
  const [token, setToken] = useState('');

  useEffect(() => {
    getSessionToken().then((newToken) => {
      setToken(newToken);
    });
  }, []);
  return <TextField label="Session Token" value={token} disabled />;
}
extend('MyExtension', render(() => <App />));
```


### Make a request to your app's backend server

After your extension has received a session token, you can include it in requests to your server. How you include the session token in the request is up to you, but we suggest including it in the request header as follows:


```typescript?title: 'JavaScript'
import {extend, Button} from '@shopify/admin-ui-extensions';

extend('MyExtension', (api, root) => {
  const sessionToken = api.sessionToken;

   const sendRequest = async () => {
    const token = await sessionToken.getSessionToken();
    const response = await fetch('https://server-url-here', {
      headers: {
       'any-header-key': token || 'unknown token',
      },
    });
    console.log('Response', response.text());
  };

  const button = root.createComponent(Button, {
    title: 'Send request',
    onClick: sendRequest,
  });
  root.append(button);
});
```

```typescript?title: 'React'
import React, {useCallback} from 'react';
import {extend, render, useSessionToken, Button} from '@shopify/admin-ui-extensions-react';

function App() {
  const {getSessionToken} = useSessionToken();

  const sendRequest = useCallback(async () => {
    const token = await getSessionToken();
    const response = await fetch('https://server-url-here', {
      headers: {
       'any-header-key': token || 'unknown token',
      },
    });
    console.log('Response', response.text());
  }, [getSessionToken]);

  return <Button title="Send request" onClick={sendRequest} />;
}

extend('MyExtension', render(() => <App />));
```


For information on how to set up your requests for each extension mode, refer to [Create and manage a product subscription app extension](/docs/apps/build/purchase-options/product-subscription-app-extensions/create-and-manage).

## Step 2: Receive a request and decode the session token

When your server receives a request from your extension that includes a session token, you need to decode it. Session tokens use the [JSON Web Token (JWT)](https://jwt.io) format. Libraries to encode and decode JWT are available for all [common server frameworks](https://jwt.io/#libraries-io).

1. Pass the following parameters to the JWT `decode` method:

- The session token received in your extension's request
- The client secret for your app
- The HS256 algorithm

      ```ruby
    JWT.decode(token_sent_from_the_extension, client_secret, true, "HS256")
    ```

The session token contains the details of the current shop and user, including the following information:

- Your shop's domain
- Your app’s client ID
- The user ID

You can use this information to establish per-user sessions, similar to an authentication cookie.

For information on the session token structure, refer to [Anatomy of a session token](/docs/apps/build/authentication-authorization/session-tokens#anatomy-of-a-session-token).

## Step 3: Validate a session token

Validate session tokens using one of the following methods:

- [Manually validate session tokens](#manually-validate-a-session-token)
- [Use the shopify app gem](#use-the-shopify-app-gem-to-validate-a-session-token)
- [Configure a Rails app to perform the validation](#configure-a-rails-app-to-validate-a-session-token).

### Manually validate a session token

To verify that a session token is coming from Shopify, you can encode a new session token using your app’s shared secret and compare it to the encoded token received from your extension.

An encoded JWT is a string with the following structure:

```json
{header}.{payload}.{signature}
```

> Note
>
> - `{header}`, `{payload}`, and `{signature}` are all Base64-encoded.
> - `{signature}` verifies that the header and payload were encoded using the shared secret and confirms that the token was generated by Shopify.
>
> For more information about the structure, refer to [Anatomy of a session token](/docs/apps/build/authentication-authorization/session-tokens#anatomy-of-a-session-token) and [JWT.io](https://jwt.io/).

1. Using the **SHA-256** algorithm, hash the decoded `{header}` and `{payload}` values from the extension session token.

1. Sign the string using JWT.

    Specify the **HS256** algorithm and use the app’s secret as the signing key.

1. Base64url-encode the result.

1. Compare the new session token with the session token received from your extension.

    If the session tokens are identical, then the request came from Shopify.

### Use the Shopify App gem to validate a session token

If your server uses the [Shopify App gem](https://github.com/Shopify/shopify_app) to validate session authentication for GraphQL requests, then requests containing a valid JWT token in the request header will automatically be authorized. An error is raised if an invalid token is received.

### Configure a Rails app to validate a session token

You can skip the following steps if any of the following criteria are met:

- The app uses Shopify App gem version 13.1.0 or newer.
- The server doesn’t use Rails.
- The server is already configured to process GraphQL requests using the Shopify App gem.

1. In `config/routes.rb`, add the following route:

    
    ```ruby
    post "/graphql_extension", to: "graphql#execute_extension"
    ```
    

1. In the `app/controllers/graphql_controller.rb` file, replace the content with the following code:

    
    ```ruby
    # frozen_string_literal: true

    # ... existing imports ...
    class GraphqlController < AuthenticatedController
      class UnauthorizedRequest < RuntimeError; end

      # If accessing from outside this domain, nullify the session
      # This allows for outside API access while preventing CSRF attacks,
      # but you'll have to authenticate your user separately
      # protect_from_forgery with: :null_session
      protect_from_forgery with: :null_session, prepend: true
      before_action :validate_request, only: [:execute_extension], prepend: true

      ENCODING_ALGORITHM = "HS256"

      # ... existing public methods

      def execute_extension
        puts "---DEBUG---: JWT VALIDATION SUCCESS!"
        # ... execute on server schema or proxy to Shopify
      end

      private

      def validate_request
        # JWT.decode(token, secret, verify, algorithm)
        #   -> takes the secret, runs it over the encoding algo, compares it with the token from the client
        JWT.decode(jwt_token_from_request, 'custom-fields-dev-secret', true, algorithm: ENCODING_ALGORITHM)
      rescue JWT::DecodeError
        raise UnauthorizedRequest
      end

      def jwt_token_from_request
        token = (/Bearer (?<token>.+)/.match(request.headers.fetch("authorization", "")) || {})[:token]
        raise UnauthorizedRequest unless token.present?
        token
      end

      # ... existing private methods
    end
    ```
    

## Step 4: Making requests to Shopify’s Admin API

To communicate with the Shopify Admin API, your extension needs to make requests through your app's backend server. You need to build an API that your extension can make requests to, which in turn makes requests to the Shopify Admin API.

## Next steps

- [Create and manage a product subscription app extension](/docs/apps/build/purchase-options/product-subscription-app-extensions/create-and-manage)