Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 55 ยท Authentication and Sessions

Online vs Offline Tokens

Understand Shopify online and offline access tokens: who they belong to, how long they live, when to use each, and how to store, rotate and choose between them in code.

When your server asks Shopify for an access token, it must choose one of two kinds. An offline token belongs to the shop: it works whenever your app needs it, with nobody signed in. An online token belongs to one staff member: it works only for a limited time and carries that person's permissions. Picking the wrong kind is one of the most common sources of "it works when I click, but fails in the background" bugs.

This lesson explains the difference, gives a simple decision rule, and shows how to store and rotate both kinds. You will build a small decision helper and a request-context checker. The real token requests are shown read-only (see Token Exchange and Access Tokens for the request itself); the runnable parts are stand-ins written in plain JavaScript.

Two questions decide everything

Ask these two questions about the code that needs the token:

  1. Is a human waiting on this request right now? If a staff member clicked a button in your embedded app, you have a session token with a user in it. If a webhook arrived or a scheduled job started, nobody is there.
  2. Must the action respect what this person is allowed to do? A staff member might have permission to edit products but not to view orders. If your app should honor that, you need an online token.
flowchart TD
  A["Code needs to call the Admin API"] --> B{"Is a staff member<br/>waiting on this request?"}
  B -- "No (webhook, job, cron)" --> O["Use the offline token"]
  B -- Yes --> C{"Must the call respect<br/>this user's permissions?"}
  C -- Yes --> N["Use an online token"]
  C -- No --> O

Background work always uses offline. User-facing work uses online only when user permissions matter.

Offline tokens: the shop's long-term key

An offline token is tied to the shop. It stays valid after the staff member closes the tab, which is exactly what you need for:

  • Webhook handlers. When Shopify posts orders/create to your server, you often need to read more data. There is no session token on that request, only the shop domain in a header.
  • Background jobs and queues. Nightly syncs, retries, bulk operations that you start now and finish later.
  • Scheduled tasks. Anything driven by a clock instead of a click.

Offline tokens are powerful because they work without a human. For the same reason they are the more sensitive secret. Historically they did not expire, and some apps still hold such tokens; newer apps can opt into expiring offline tokens with refresh tokens, which limit the damage of a leak. Whatever your lifetime, never expose one to the browser and delete it when the app is uninstalled.

Online tokens: a person at the keyboard

An online token is tied to a shop and a staff user. Shopify reports which user it belongs to, and the token can do only what both the app's scopes and that user's own permissions allow. It also expires; the documented lifetime for online tokens has been 24 hours, but read the current documentation instead of hard-coding it.

Use an online token when:

  • The feature must follow the user's role, for example showing financial data only to people who may see it.
  • You want an audit trail that says "this staff member did this", because actions are attributed to the user.
  • The work finishes within the request the user started.

Because it expires and belongs to a person, an online token is a poor choice for anything that outlives the request.

Side by side

Offline Online
Belongs to The shop One staff user in one shop
Needs a logged-in user No Yes
Typical lifetime Long (or expiring with refresh) Short, about a day
Permissions App scopes App scopes narrowed by the user's permissions
Good for Webhooks, jobs, bulk work Interactive admin screens
Store keyed by Shop Shop and user

Many apps use only offline tokens and enforce their own roles inside the app. That is a legitimate, simpler design. Add online tokens when you really need Shopify's per-user permission check.

What the code looks like

In the official React Router template the choice is made for you. The default authenticate.admin(request) call gives you an admin client based on the stored session, and the template configuration decides whether online or offline tokens are requested. If you use the lower-level API, you pass the kind explicitly when you exchange. Roughly, and read-only because this site cannot call Shopify:

TypeScript
// Read-only sketch; the exact helper names depend on your library version.
// A webhook handler has no user, so it asks for the shop's offline session.
export const action = async ({ request }: ActionFunctionArgs) => {
  const { shop, topic, admin } = await authenticate.webhook(request);

  if (!admin) {
    // The app was uninstalled or the session was deleted; nothing to call.
    return new Response();
  }

  // admin.graphql(...) uses the offline token stored for `shop`.
  await admin.graphql(`#graphql
    query { shop { name } }`);

  return new Response();
};

The important point is not the exact function names, which change between releases, but the shape: webhook and job code looks up the offline session by shop, while interactive code uses the session that matches the current user.

A decision helper

The first stand-in turns the two questions into a function. It takes a description of the situation and returns which token kind to use and why.

Node.js Which token should this code use?

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.

The "big export" case is the interesting one. The user's permissions matter at the moment of the click, but the work runs for minutes. A common design checks the permission up front with the online token, then queues the job and runs it with the offline token.

Choosing at run time

The second stand-in models a server that receives different kinds of requests and has two stored tokens. It picks the right one, refuses to use an expired online token, and shows what happens in a background job that wrongly tries an online token.

Node.js Using the right stored token per request

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.

The failing "job tries online token" line is the classic bug: code written while testing in the admin works, then breaks the first time a webhook or queue worker runs it, because there is no user.

Storing and rotating

A few habits keep both kinds safe:

  • Key them differently. Offline by shop; online by shop and user id. Mixing the keys lets a user's short-lived token overwrite the shop's long-lived one.
  • Keep the expiry and the scopes with each record. Expiry tells you when to exchange again; scopes let you detect that a merchant approved new access since you stored the token (Managed Installation and Access Scopes).
  • Rotate by replacing. When you refresh or re-exchange, overwrite the old record. With expiring offline tokens, store the new refresh token as well.
  • Encrypt at rest if your database or backups might be read by people who should not see tokens.
  • Delete on uninstall and when a shop-redact request arrives (Privacy, GDPR and Mandatory Webhooks).
  • Log the kind, never the value. "Used offline token for shop-a" is useful; the token itself must never appear in logs.

When a staff member is removed from a store, their online tokens stop being useful, but your database does not know that. Treat online records as a cache you can drop at any time, and keep anything long-lived under the offline token.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A webhook handler needs to read extra order data from the Admin API. Which token should it use?

    A webhook request has no staff member and no session token. Only the shop-bound offline token works without a user present.
  2. 2. Which statement about online tokens is correct?

    An online token is bound to a shop and a staff user, expires after a limited time, and cannot do more than that user is allowed to do.
  3. 3. How should you key stored tokens?

    Separate keys prevent a user's short-lived token from replacing the shop's token, and let you drop online records without touching the offline one.
  4. 4. A staff member starts a ten-minute export and the permission check must be honored. What is a sound design?

    Verify what the user may do at request time, then hand the long-running work to a job that uses the offline token.

Summary

  • Offline tokens belong to the shop and work without a user; online tokens belong to one staff member, expire, and respect that person's permissions.
  • Use offline for webhooks, queues and schedules; use online only when per-user permissions or attribution matter.
  • Many apps use offline tokens only and enforce roles themselves.
  • Key offline records by shop and online records by shop and user, store expiry and scopes, and rotate by replacing.
  • Never expose tokens to the browser or logs, and delete them on uninstall.

Next: Authenticated Requests and Route Protection puts these pieces behind a single check on every route.