Choose a version:

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

Anchor to Use casesUse 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

Anchor to Properties and methodsProperties and methods

The shopify global object 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.

Anchor to 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.

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

);

}

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

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

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

Anchor to Best practicesBest 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.

Was this page helpful?