A session token is a mechanism that lets your embedded app authenticate the requests that it makes between the client side and your app's backend.


> Note:
> All embedded apps need to use session tokens because third-party cookies won't work with browsers that restrict cross-domain data access.
> If your embedded app still uses cookies and could pose a risk to users, then as part of our [app audit process](/docs/apps/launch/app-store-review/app-audits) you might be contacted and requested to migrate your app to use session tokens. This request will require immediate action.

The following video provides a short introduction to session tokens:

<div class="video-embed-wrapper">
  <figure>
    <iframe src="https://www.youtube.com/embed/UJxg7Cbrqo0?cc_lang_pref=&cc_load_policy=1" width="800" height="450" allowfullscreen></iframe>
  </figure>
</div>


## How session tokens work

This section describes the authentication and request flows associated with session tokens, and the lifetime of a session token. It also provides information about implementing both OAuth and session token authentication for embedded apps.

### Authentication flow using a session token

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

After the frontend code has loaded, your app calls a [Shopify App Bridge action](/docs/api/app-bridge/previous-versions/actions) to get the session token. Your app includes the session token in an authorization header when it makes any HTTPS requests to its backend.

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/partners/jwt-auth-flow-d38569ac76038a22e32b79e860640088dde0212d2bc3b0d8132debd6158264c6.png" class="lazyload" width="2331" height="1420"></figure>

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

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/auth/jwt-request-flow-06340ad4e59fa2a6a104da1f0d4827081431da7efa7e6742d07531302b8e5417.png" class="lazyload" width="1548" height="886"></figure>

### 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 make sure that stale tokens aren't used.

### OAuth and session tokens

> Tip:
> You can use [Shopify CLI](/docs/apps/build/cli-for-apps) to generate a starter app with boilerplate code that handles authentication and authorization. The starter app includes code for an embedded app that uses [session tokens](/docs/apps/build/authentication-authorization/session-tokens) and [token exchange](/docs/apps/build/authentication-authorization/access-tokens/token-exchange).


Session tokens are for authentication, and aren't a replacement for [authorization](/docs/apps/build/authentication-authorization#authorization). Learn more about the [difference between authentication and authorization](/docs/apps/build/authentication-authorization#authentication-vs-authorization).

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 user's shop.

For example, to [make authenticated requests](/docs/apps/build/authentication-authorization/access-tokens/token-exchange#step-3-make-authenticated-requests) to the [GraphQL Admin API](/docs/api/admin-graphql), your app must store the access token it receives during the OAuth flow. To contrast, session tokens are used by your app's backend to verify the embedded request coming from your app's frontend.

The following diagram shows the authentication process using session tokens and API access tokens:

![Diagram showing authentication process using sessions tokens and API access tokens](/assets/partners/auth-mechanisms.png)

## Anatomy of a session token

Session tokens use the [JSON Web Token (JWT)](https://jwt.io) format and contain information about the merchant that's currently using your embedded app.

A session token consists of a header, payload, and signature. For an interactive example, refer to [JWT.io](https://jwt.io/), where you can experiment with setting different values for each section. Shopify recommends that you use your 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](https://www.npmjs.com/package/@shopify/app-bridge), which generates and includes the session token in your requests. On the backend, you can use middleware similar to `validateAuthenticatedSession` in [@shopify/shopify-app-express](https://github.com/Shopify/shopify-app-js/blob/main/packages/apps/shopify-app-express/docs/reference/validateAuthenticatedSession.md).

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

### Header

The values in the header are constant and never change.

```json
{
  "alg": "HS256",
  "typ": "JWT"
}
```

- `alg`: The algorithm used to encode the JWT.
- `typ`: The [(type) header parameter](https://tools.ietf.org/html/rfc7519#section-5.1) used by session token to declare the media type.

### Payload

```json
{
  "iss": "<shop-name.myshopify.com/admin>",
  "dest": "<shop-name.myshopify.com>",
  "aud": "<client ID>",
  "sub": "<user ID>",
  "exp": "<time in seconds>",
  "nbf": "<time in seconds>",
  "iat": "<time in seconds>",
  "jti": "<random UUID>",
  "sid": "<session ID>"
  "sig": "<signature>"
}
```

- `iss`: The shop's admin domain.
- `dest`: The shop's domain.
- `aud`: The client ID of the receiving app.
- `sub`: The [User](/docs/api/admin-rest/latest/resources/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.
- `sig`: Shopify signature.

### Example payload

```json
{
 "iss"=>"https://exampleshop.myshopify.com/admin",
 "dest"=>"https://exampleshop.myshopify.com",
 "aud"=>"client-id-123",
 "sub"=>"42",
 "exp"=>1591765058,
 "nbf"=>1591764998,
 "iat"=>1591764998,
 "jti"=>"f8912129-1af6-4cad-9ca3-76b0f7621087",
 "sid"=>"aaea182f2732d44c23057c0fea584021a4485b2bd25d3eb7fd349313ad24c685",
 "sig"=>"f07cf3740270c17fb61c700b2f0f2e7f2f4fc8cc48426221738f7a39e4c475bf",
}
```

> Note:
> All times are in UNIX timestamp format.

## Limitations and considerations

Session token authentication is fully supported for single-page apps. For more information, refer to [Getting started with session token authentication](/docs/apps/build/authentication-authorization/session-tokens/set-up-session-tokens).

If you have a multi-page app, then it might be possible 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. For an example, refer to the [Turbolinks and JWT sample app](https://github.com/Shopify/turbolinks-jwt-sample-app).

## Sample apps

- [Sample single-page embedded app using Rails and React](https://github.com/Shopify/next-gen-auth-app-demo)
- [Sample server-side rendered Rails app converted using Turbolinks](https://github.com/Shopify/turbolinks-jwt-sample-app)

## Next steps

- Set up your embedded app to [authenticate using session tokens](/docs/apps/build/authentication-authorization/session-tokens/set-up-session-tokens).