Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 55 ยท Authentication and Sessions

Session Tokens for Embedded Apps

Understand Shopify session tokens: why cookies fail inside the admin iframe, the JWT claims iss, dest, aud and exp, and how to verify the signature on your server.

An embedded Shopify app does not open in its own browser tab. It runs inside an iframe in the Shopify admin, on a different domain than the admin itself. That one fact breaks the way most web apps remember who is logged in. This lesson explains the problem, the replacement Shopify provides (the session token), and how your server checks one.

You should already know what a scope is from Managed Installation and Access Scopes. Here we answer a different question: when a request arrives at your server, how do you know it came from a real merchant user, inside a real admin, for your app?

Why cookies fail in an iframe

A classic login stores a session id in a cookie. Inside the admin iframe that stops working reliably:

  • Browsers treat your app as third-party content inside the admin page and increasingly block or partition third-party cookies.
  • Some browsers (Safari most strictly) refuse them outright, and private windows block more.
  • Cookies can leak across tabs and users in ways that are hard to reason about.

So Shopify moved embedded apps to a header-based design. Your app's front end asks App Bridge (a script provided by Shopify, loaded from Shopify's CDN) for a short-lived token and sends it on each request to your backend. The token is not stored in a cookie, so nothing depends on browser cookie policy.

sequenceDiagram
  participant A as Shopify admin
  participant F as Your app UI (iframe)
  participant S as Your server
  A->>F: Loads your app URL with App Bridge
  F->>A: shopify.idToken()
  A-->>F: Signed session token (about 1 minute)
  F->>S: Request with Authorization: Bearer token
  S->>S: Verify signature and claims
  S-->>F: Data for that shop and user

The token is created by Shopify on demand, sent in a header, and checked by your server on every request.

What a session token is

A session token is a JSON Web Token (JWT). A JWT is three base64url-encoded parts joined by dots:

TEXT
HEADER.PAYLOAD.SIGNATURE
  • The header names the algorithm. Shopify session tokens use HS256, which means HMAC with SHA-256.
  • The payload holds the claims (facts) as JSON.
  • The signature is an HMAC over HEADER.PAYLOAD computed with a secret key.

The key is your app's client secret, which only you and Shopify know. That is why a valid signature proves Shopify issued the token: nobody else can produce it. The payload is only encoded, not encrypted, so anyone holding a token can read it. Never put secrets into claims, and never log full tokens.

The claims you must understand

A decoded payload looks like this (values shortened):

JSON
{
  "iss": "https://example-store.myshopify.com/admin",
  "dest": "https://example-store.myshopify.com",
  "aud": "your-app-client-id",
  "sub": "42",
  "exp": 1767225660,
  "nbf": 1767225600,
  "iat": 1767225600,
  "jti": "a1b2c3d4-0000-0000-0000-000000000000",
  "sid": "session-id-from-shopify"
}
  • iss (issuer): the shop's admin URL that issued the token.
  • dest (destination): the shop the request is about. This is how you learn which merchant is calling.
  • aud (audience): your app's client id. A token minted for another app must be rejected by yours.
  • sub (subject): the id of the staff user. Treat it as an opaque string.
  • exp, nbf, iat: expiry, not-before and issued-at, in seconds since 1970. Session tokens live for only about a minute, which limits the damage if one leaks.
  • jti and sid: unique ids for the token and the admin session.

Verifying a token on the server

Verification has fixed steps, and skipping any of them is a vulnerability:

  1. Split the token into three parts and check the algorithm is the one you expect (never accept none).
  2. Recompute the HMAC over HEADER.PAYLOAD with your client secret and compare it with the signature in constant time.
  3. Check exp and nbf against the clock, with a small tolerance for clock skew.
  4. Check that aud equals your client id.
  5. Check that the host of iss equals the host of dest, and that dest is a valid shop domain.

Only then may you trust dest as the shop for this request.

In a real app you rarely write this yourself. The React Router template calls authenticate.admin(request) (see Authenticated Requests and Route Protection), which performs all of these checks for you. Understanding them still matters, because you will meet them in tests, custom backends and security reviews.

A runnable JWT builder

This first stand-in builds a session-token-shaped JWT using Node's crypto module. It is not issued by Shopify: we play both sides, using a made-up secret and fixed timestamps so the output is the same on every run.

Node.js Build and decode a session-style JWT

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that decoding needed no secret. That is the point: the payload is readable by anyone; only the signature needs the key.

A runnable verifier

The next stand-in implements the five verification steps. It tries a good token and several bad ones, and shows which check rejects each.

Node.js Verify a token and reject the bad ones

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Each rejection comes from a different line. The "edited payload" case is the important one: an attacker who changes dest to a different shop invalidates the signature, because the HMAC was computed over the original payload. The "not a shop" case is signed correctly (we signed it ourselves) and is rejected only by the domain check, which is why that check exists in addition to the signature.

Never accept a token just because it decodes. Decoding proves nothing; only the signature check against your client secret does. Also never copy dest from a query string or a header of your own invention: take the shop from a verified token.

Sending the token from the front end

In the embedded UI you get a token on demand and attach it to requests to your own backend:

JavaScript
// In the embedded app's browser code (read-only)
const token = await shopify.idToken();

const response = await fetch("/api/products", {
  headers: { Authorization: `Bearer ${token}` },
});

The shopify.idToken() call returns a fresh token each time it is needed, so you do not store or refresh anything. In the official template the browser's fetch is already wrapped by App Bridge, so requests to your own origin carry the header without extra code. On the first load of a page, the token can also arrive as an id_token query parameter that your server verifies.

What a session token is not

A session token proves who is calling your server. It does not let you call Shopify's Admin API. For that you need an access token, and you obtain one by trading the session token. That trade is the topic of the next lesson.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why do embedded apps use session tokens instead of cookies?

    Your app runs in an iframe on another domain, so browsers treat its cookies as third-party and increasingly block them. A bearer token in a header does not depend on cookie policy.
  2. 2. Which claim tells your server which shop the request is for?

    dest is the destination shop URL. aud is your app's client id, jti is a unique token id and nbf is the not-before time.
  3. 3. What key signs a session token, and who can read its payload?

    Session tokens are HS256 JWTs signed with your client secret. The payload is base64url-encoded, not encrypted, so never put secrets in it and never log whole tokens.
  4. 4. A token has a valid signature but its aud is a different app's client id. What should you do?

    The audience check ensures a token minted for another app cannot be used against yours. Verify aud on every request.
  5. 5. Does a verified session token let you call the Admin GraphQL API?

    A session token identifies the caller to your backend. Admin API calls need an access token, which you obtain through token exchange.

Summary

  • Embedded apps run in an iframe, where cookies are unreliable, so Shopify uses short-lived session tokens.
  • A session token is an HS256 JWT signed with your client secret; its payload is readable but tamper-proof.
  • Key claims: dest (the shop), aud (your client id), iss, sub (user), and exp/nbf/iat (about a one-minute lifetime).
  • Verify the algorithm, the signature in constant time, the time window, the audience, and that iss and dest agree and name a shop.
  • Get tokens in the browser with shopify.idToken() and send them as Authorization: Bearer.
  • A session token authenticates the caller to your server; Admin API access needs an access token.

Next: Token Exchange and Access Tokens turns a session token into an access token for the Admin API.