---
title: Session Token API
description: >-
  The Session Token API provides a method to request a signed JSON Web Token
  (JWT) from Shopify. Use this API to authenticate requests from your checkout
  extension to your application server.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/platform-apis/session-token-api
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/platform-apis/session-token-api.md
---

# Session Token API

The Session Token API provides a method to request a signed JSON Web Token (JWT) from Shopify. Use this API to authenticate requests from your checkout extension to your application server. The token's claims are signed with your app secret, so your server can verify they came from Shopify unaltered.

Using `fetch()` from a checkout extension requires the [`network_access` capability](https://shopify.dev/docs/apps/build/checkout/capabilities#network-access) to be enabled in your extension configuration.

The `sub` claim in the decoded token is present only when the buyer is logged in and your app has permission to read customer accounts. For anonymous buyers, the claim is absent.

### Use cases

* **Authenticate server requests**: Pass the session token as a bearer token in `fetch()` calls to your backend so your server can verify the request came from a Shopify checkout.
* **Identify the customer**: Extract the customer's GID from the optional `sub` claim when the buyer is logged in and your app has permission to read customer accounts.
* **Validate checkout context**: Use the token claims to confirm the shop, extension, and checkout context on your server before processing a request.

### Support Targets (33)

### Supported targets

* [purchase.​address-autocomplete.​format-suggestion](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/address#format-a-selected-suggestion-)
* [purchase.​address-autocomplete.​suggest](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/address#suggest-address-completions-)
* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* purchase.​checkout.​chat.​render
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* purchase.​thank-you.​chat.​render
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

### Properties and methods

The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides session token capabilities for the current checkout. Access the following properties and methods on `shopify` to request a signed JSON Web Token (JWT) for server authentication. Available to `purchase` extension targets.

* **sessionToken**

  **SessionToken**

  **required**

  The session token providing a set of claims as a signed JSON Web Token (JWT).

  The token has a TTL of five minutes.

  If the previous token expires, this value reflects a new session token with a new signature and expiry.

  Learn more about [session tokens](https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens).

### 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.

  ```ts
  () => Promise<string>
  ```

Examples

### Examples

* ####

  ##### Description

  Request a session token and pass it to your application server as a bearer token. This example calls \`shopify.sessionToken.get()\` and includes the token in a \`fetch()\` request header so your server can verify the signed claims. > Note: You'll need to \[enable the \`network\_access\` capability]\(/docs/apps/build/checkout/capabilities#network-access) to use \`fetch()\`.

  ##### jsx

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

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

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

    useEffect(() => {
      async function queryApi() {
        const token =
          await shopify.sessionToken.get();

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

        console.log('API response', apiResponse);
      }

      queryApi();
    }, [sessionToken]);

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

* ####

  ##### Description

  Review the structure of a decoded session token. The contents are signed using your shared app secret. The optional \`sub\` claim contains the customer's GID if they're logged in and your app has permission to read customer accounts. > Caution: Your app server can trust only the claims within the session token. It can't use the token to trust the entire HTTP request. See \[security considerations]\(/docs/apps/build/checkout/capabilities#network-access) for details.

  ##### session-token.jwt

  ```json
  {
    // 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>"
  }
  ```

***

## Best practices

* **Request a fresh token before each server call**: Session tokens have a TTL of five minutes. Always call `sessionToken.get()` immediately before making a `fetch()` request rather than storing a previously retrieved token string. Calling `sessionToken.get()` before each `fetch()` doesn't significantly impact performance, because Shopify caches the token internally and returns it if it's still valid.
* **Don't trust the full HTTP request**: Validate only the signed token claims. Your server can trust the claims inside the session token, but it can't use the token to trust the entire HTTP request body or headers.

***