Session tokens in detail

This guide explains the technical details of session tokens and outlines the role that they play in authenticating an embedded Shopify app.

How session tokens work

A session token, also known as a JSON web token (JWT), lets your app authenticate the requests that it makes between the client side and your app's backend. The session token also contains information about the merchant who's currently using your embedded app.

The following video provides a short introduction to session tokens:

Authentication flow using a session token

When your embedded app first loads, it's unauthenticated and serves up the frontend code for your app. The app renders a user interface skeleton or loading screen to the user.

After the frontend code has loaded, the app calls a Shopify App Bridge action to get the session token. Your app includes the session token in an authorization header when it makes any HTTPS requests to its backend.

Request flow using a session token

The session token is signed using the shared secret between your app and Shopify so that your backend can verify if the request is valid.

Lifetime of a session token

The lifetime of a session token is one minute. Session tokens must be fetched using Shopify App Bridge on each request to ensure that stale tokens aren't used.

OAuth and session tokens

Session tokens aren't a replacement for implementing OAuth with Shopify.

Unlike API access tokens, session tokens can't be used to make authenticated requests to Shopify APIs. An API access token is what you use to send requests from your app's backend to Shopify so that you can fetch specific data from the merchant's shop.

For example, to make authenticated requests to the Admin API, your app must store the access token it receives during the OAuth flow. For more information, refer to Make authenticated requests.

To contrast, session tokens are used by your app's backend to verify the embedded request coming from your app's front end.

Third-party cookies vs session tokens

Many embedded apps rely on third-party cookies to verify the merchant's identity on the Shopify admin. When the app loads, it sets a cookie in the browser. The app keeps track of the cookie and any other relevant information in a session on its server. The browser sends the cookie to the server with every request.

Apps that aren't embedded can rely on first-party cookies set by your app, so you don't need to use session tokens. Embedded apps, however, can no longer rely on cookies in the same way, so you should use session tokens instead.

Authentication through session tokens doesn't rely on cookies for embedded apps to authenticate merchants. Instead, your app frontend sends the session token to its backend with every request. The backend then uses the session token to determine the user's identity.

Anatomy of a session token

A session token consists of a header, payload, and signature. For an interactive example, refer to JWT.io, where you can experiment with setting different values for each section. Shopify recommends that you use a test app's credentials when testing on JWT.io.

For the most part, you shouldn't have to manage the anatomical details of session tokens. In most scenarios, you'll use a library, such as authenticated_fetch from app-bridge-utils, which generates and includes the session token in your requests. On the backend, you can use verifyRequest from koa-shopify-auth to validate your session token.

After a Shopify session token is decoded, it has the following fields:

The values in the header are constant and never change.

  • alg: The algorithm used to encode the JWT.
  • typ: The (type) header parameter used by session token to declare the media type.

Payload

  • iss: The shop's admin domain.
  • dest: The shop's domain.
  • aud: The API key of the receiving app.
  • sub: The user that the session token is intended for.
  • exp: When the session token expires.
  • nbf: When the session token activates.
  • iat: When the session token was issued.
  • jti: A secure random UUID.
  • sid: A unique session ID per user and app.

Example payload

Single-page apps and multi-page apps

The following section provides information on implementing session tokens for single-page apps (SPA) and multi-page server-side rendered apps (non-SPA).

Single-page apps

Single-page apps interact with the user by dynamically updating the current web page with new data from the server. Shopify's sample node app is a single-page app.

It's easier to enable session token authentication on single-page apps. Without cookies, every new page load needs to be a two-step process. The first step is an unauthenticated load of the frontend JavaScript to create an instance of Shopify App Bridge. The second step uses the session token to start fetching the merchant data.

For more information, refer to Authenticate an embedded app using session tokens.

Multi-page apps

Multi-page apps load entirely new pages when the user requests additional data, rather than updating a single page. Requests for new pages aren't usually handled by JavaScript, so App Bridge needs to be loaded again for each page request. Since App Bridge must be loaded multiple times, the implementation of session tokens is more complicated.

If you have a multi-page app, then you might be able to convert it to behave as if it were a single-page app using Turbolinks. You can only use session tokens for a multi-page app if you convert it to behave like a single-page app.

Sample apps

Next steps