Shopify Auth & Sessions

The confusion to clear up first

There are two completely different tokens in a Shopify app. They have similar names, they do opposite jobs, and mixing them up is the source of an enormous share of beginner bugs.

What a "session" actually is

Despite the name, it is not a login cookie. It is simply a row in your database holding one shop's access token.

model Session {
  id          String    @id      // "offline_shop.myshopify.com"
  shop        String             // "shop.myshopify.com"
  accessToken String             // the secret for calling the API
  scope       String?            // permissions this token has
  isOnline    Boolean   @default(false)
  expires     DateTime?
}

That is why sessionStorage: new PrismaSessionStorage(prisma) appears in shopify.server.js — it tells the library to keep these rows in your database, so installs survive a restart.

One row per installed shop. Ten shops installed, ten rows.

Offline vs online sessions

Unless you turned on useOnlineTokens, you are using offline sessions. Keep it that way while you are learning — background jobs and webhooks need a token that works with nobody logged in.

How a request gets authenticated

Modern Shopify apps use token exchange. Here is what happens on a page load, in order:

1. Your page loads inside the Shopify admin. App Bridge gets a fresh session token and attaches it to the request.
2. authenticate.admin(request) verifies that token is genuine and identifies the shop.
3. It looks for a stored session for that shop.
4. If none exists (or it is no longer valid), it exchanges the session token for an access token and saves it.
5. You get back session and admin.

You never write any of this. You write one line.

The four authenticate functions

Which one you need depends entirely on who is calling you.

In a page

export const loader = async ({ request }) => {
  const { session, admin } = await authenticate.admin(request);

  session.shop;    // "shop.myshopify.com" — scope your DB queries with this
  session.id;      // "offline_shop.myshopify.com" — the session row itself
  admin.graphql;   // call the Shopify API
};

In a background job

A cron job at 3am has no request to authenticate, so it loads the stored token directly:

const { admin } = await unauthenticated.admin("shop.myshopify.com");
await admin.graphql(`...`);

This works even though offline tokens expire: before using the stored token, the library checks it and refreshes it if needed. A job never has to log in — another reason to stay with offline sessions.

The security rule you must not forget

Your database holds data for every shop that installed your app. Nothing stops one shop's request from reading another's rows — except your where clause.

// WRONG — returns every shop's products to whoever asks
const products = await db.product.findMany();

// RIGHT — scoped to the shop that made this request
const products = await db.product.findMany({
  where: { shop: session.shop },
});

// Deletes must be scoped too, or one shop can delete another's row
await db.product.deleteMany({
  where: { id: Number(form.get("id")), shop: session.shop },
});

return { session };              // leaks the access token!
return { shop: session.shop };    // safe

Scopes: asking for permission

A scope is one permission, like read_products. Your app can only do what its scopes allow, and they live in two places:

# shopify.app.toml
[access_scopes]
scopes = "read_products,write_products"

# SCOPES env var — shopify.server.js reads it at runtime.
# shopify app dev sets it for you; on your server you set it.
SCOPES=read_products,write_products

Adding a scope means: update both places, deploy, and the merchant is asked to approve the new permission. Until they do, the new capability does not work. (On a dev store, a running shopify app dev grants new scopes automatically.)

Uninstall and reinstall

When a merchant uninstalls, Shopify immediately revokes the access token and calls your app/uninstalled webhook. Your stored token is now a dead string.

await db.session.deleteMany({ where: { shop } });

On reinstall there is no session row, so the first request fetches a fresh token — in the shopify app dev terminal you see No valid session found, then Requesting offline access token. The merchant sees nothing.

The one-minute session token problem

Remember: session tokens expire in about a minute. Usually irrelevant, because requests take milliseconds.

It becomes very relevant with slow requests — uploading a large file, for example. If the upload takes longer than the token's life, the request fails with a 401 that makes no sense, because you were logged in.

Error decoder

Checklist for every new route

• Called by a merchant? Start with authenticate.admin(request).
• Called by Shopify or a shopper? Use authenticate.webhook or authenticate.public.appProxy — and remember these files must not be named app.*.
• Every database query has shop in its where clause — including deletes.
• The loader returns only the fields the page displays. Never the session.
• New capability? Scope added to the TOML — and to SCOPES on your production server (Note 11). In development the CLI handles it.

Cheat sheet

# two tokens
session token   browser → your app   ~1 minute   App Bridge handles it
access token    your app → Shopify   long-lived  stored in your DB

# who is calling?
merchant in admin   authenticate.admin(request)
Shopify webhook     authenticate.webhook(request)
storefront shopper  authenticate.public.appProxy(request)
scheduled job       unauthenticated.admin(shop)

# what you get back
session.shop    which shop — scope every query with this
admin.graphql   call the Shopify API

# never
db.product.findMany()        unscoped — leaks other shops
return { session }           leaks the access token
@relation to Session         breaks uninstall (Note 05)