Building embedded apps using session tokens

Embedded apps on Shopify admin use session tokens to authenticate. Session tokens contain information about the merchant who's logged into the Shopify admin.

Why should I use session tokens?

Browsers have started implementing stricter restrictions on cross domain data access as a result of increased privacy concerns. Because embedded apps are hosted inside iframes and they're on a different domain than the Shopify admin, these restrictions are directly applicable. Managing embedded app sessions on a browser through cookies isn't an option.

For more information about the measures taken to remove third-party cookie support by browsers, refer to the following articles:

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.

Session token-based authentication 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.

Session tokens and OAuth

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.

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

How session token-based authentication works

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 an App Bridge action to get the session token JWT (JSON web token). It includes the session token in an authorization header when it makes any HTTPS requests to its backend.

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.

Authentication flow using a session token

Request flow using a session token

Authentication mechanisms using session tokens and access tokens

Anatomy of a session token

After a Shopify session token JWT (JSON Web Token) is decoded, it has the following fields:

The values in the header are constant and never change.

{
  "alg": "HS256",
  "typ": "JWT"
}
  • alg: The algorithm used to encode the JWT.
  • typ: The type header used by session token to declare the media type.

Payload

{
  "iss": "<shop-name.myshopify.com/admin>",
  "dest": "<shop-name.myshopify.com>",
  "aud": "<api key>",
  "sub": "<user ID>",
  "exp": "<time in seconds>",
  "nbf": "<time in seconds>",
  "iat": "<time in seconds>",
  "jti": "<random UUID>",
  "sid": "<session ID>"
}
  • 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

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

Tutorials

Sample apps