Choose a version:

Session Token API

The Session Token API lets you authenticate requests from your extension to your app's backend using a signed JSON Web Token (JWT). Use this API to get a token that your backend can verify using your app's shared secret, confirming the request came from a legitimate Shopify extension.

Anchor to Use casesUse cases

Authenticate backend requests: Pass a session token as a Bearer token in API calls to your app's backend so you can verify the request came from your extension.
Identify the customer: Read the optional sub claim in the token to get the customer's GID when they're signed in and your app has access to protected customer data.
Verify the shop: Use the dest claim to confirm which shop the request is associated with, ensuring your backend responds with the correct data.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides session token functionality for customer account extensions. Access the following properties on shopify to retrieve signed tokens for authenticating requests to your app's backend.

Anchor to sessionToken sessionToken required: Authenticates requests between your extension and your app backend. Call get() to retrieve a signed JWT containing the customer ID, shop domain, and expiration time, then verify it server-side. For more information, refer to the Session Token API.

SessionToken

Authenticates requests between your extension and your app backend. Use session tokens to verify the identity of the buyer and the shop context when making server-side API calls. The token is a signed JWT that contains claims such as the customer ID, shop domain, and expiration. The `sub` claim in the decoded token is present only when the buyer is logged in and the app has permission to read customer accounts. Absent for anonymous buyers.

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 returns cached tokens when possible, so you don't need to worry about storing these tokens yourself.
```
() => Promise<string>
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useEffect} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

useEffect(() => {

async function queryApi() {

// Request a new (or cached) session token from Shopify

const token =

await shopify.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();

}, []);

return (

<s-banner>

See console for API response

</s-banner>

);

}

Examples

Description

Retrieve a session token and pass it as a Bearer token to authenticate a request to your app's backend. This example uses `shopify.sessionToken.get()` to obtain the token and includes it in the `Authorization` header of a fetch call.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  useEffect(() => {
    async function queryApi() {
      // Request a new (or cached) session token from Shopify
      const token =
        await shopify.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();
  }, []);

  return (
    <s-banner>
      See console for API response
    </s-banner>
  );
}

Description

Review the structure of a decoded session token to understand the available claims. This example shows the JSON payload including the `dest`, `aud`, `exp`, and optional `sub` claims.

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>"
}

Description

Send the session token to your app backend to identify the signed-in customer. Your backend decodes and verifies the token, then returns the customer ID. This requires [access to protected customer data](/docs/apps/store/data-protection/protected-customer-data).

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useEffect, useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [customerId, setCustomerId] =
    useState(null);

  useEffect(() => {
    async function identify() {
      const token =
        await shopify.sessionToken.get();
      const response = await fetch(
        'https://my-app.com/api/customer',
        {
          headers: {
            Authorization: `Bearer ${token}`,
          },
        },
      );
      const {customerId} =
        await response.json();
      setCustomerId(customerId);
    }
    identify();
  }, []);

  return (
    <s-text>
      {customerId
        ? `Customer: ${customerId}`
        : 'Loading...'}
    </s-text>
  );
}

Anchor to Best practicesBest practices

Request tokens close to usage: Call shopify.sessionToken.get() immediately before making a request rather than storing the token for later, since tokens expire after 5 minutes.
Verify tokens server-side: Always validate the token signature, expiration (exp), and audience (aud) on your backend using your app's shared secret.
Handle token errors gracefully: Wrap token retrieval and fetch calls in try-catch blocks so your extension can display a meaningful message if authentication fails.

Anchor to LimitationsLimitations

Session tokens expire after 5 minutes. Your backend must handle expired tokens and your extension should request a new token for each request.
The sub claim is only present when the customer is signed in and your app has the read_customers scope. Don't rely on it being available in all contexts.
Session tokens are signed JWTs intended for your backend only. Don't expose sensitive claims to the customer or use them for client-side authorization decisions.

Was this page helpful?