Authentication and Access Scopes

// public/app.js
const idToken = await shopify.idToken();

const response = await fetch('/exchange/offline', {
  method: 'POST',
  headers: { Authorization: `Bearer ${idToken}` },
});

{
  "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"
}

// id-token.mjs
import { createHmac, timingSafeEqual, randomUUID } from 'node:crypto';

const b64u = (buf) => Buffer.from(buf).toString('base64url');

export function validateIdToken(token, { clientId, clientSecret, now = Math.floor(Date.now() / 1000) }) {
  const parts = token.split('.');
  if (parts.length !== 3) throw new Error('not a JWT');
  const [h, p, s] = parts;
  const header = JSON.parse(Buffer.from(h, 'base64url').toString());
  if (header.alg !== 'HS256') throw new Error(`unexpected alg ${header.alg}`);
  const expected = createHmac('sha256', clientSecret).update(`${h}.${p}`).digest();
  const given = Buffer.from(s, 'base64url');
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) throw new Error('bad signature');
  const c = JSON.parse(Buffer.from(p, 'base64url').toString());
  if (!(c.exp > now)) throw new Error('token expired (exp)');
  if (!(c.nbf <= now)) throw new Error('token not yet valid (nbf)');
  if (c.aud !== clientId) throw new Error('audience is not this app (aud)');
  if (new URL(c.iss).hostname !== new URL(c.dest).hostname) throw new Error('iss and dest hosts differ');
  return c;
}

// Test helper: signs a token shaped like the one App Bridge issues (placeholder secret only).
export function signIdToken(claims, secret) {
  const h = b64u(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
  const p = b64u(JSON.stringify(claims));
  const s = b64u(createHmac('sha256', secret).update(`${h}.${p}`).digest());
  return `${h}.${p}.${s}`;
}

export function sampleClaims(clientId, now = Math.floor(Date.now() / 1000)) {
  return {
    iss: 'https://pocket-coffee.myshopify.com/admin',
    dest: 'https://pocket-coffee.myshopify.com',
    aud: clientId,
    sub: '42',
    exp: now + 60,
    nbf: now - 5,
    iat: now - 5,
    jti: randomUUID(),
    sid: 'a'.repeat(64),
  };
}

// id-token-demo.mjs
import { validateIdToken, signIdToken, sampleClaims } from './id-token.mjs';

const clientId = '00000000000000000000000000000000';
const clientSecret = 'placeholder-client-secret-not-real';
const good = signIdToken(sampleClaims(clientId), clientSecret);
console.log('valid token      ->', validateIdToken(good, { clientId, clientSecret }).dest);

const now = Math.floor(Date.now() / 1000);
const cases = {
  'expired':        signIdToken({ ...sampleClaims(clientId), exp: now - 1 }, clientSecret),
  'wrong audience': signIdToken({ ...sampleClaims('11111111111111111111111111111111') }, clientSecret),
  'host mismatch':  signIdToken({ ...sampleClaims(clientId), dest: 'https://other.myshopify.com' }, clientSecret),
  'wrong secret':   signIdToken(sampleClaims(clientId), 'another-secret'),
};
for (const [name, tok] of Object.entries(cases)) {
  try { validateIdToken(tok, { clientId, clientSecret }); console.log(name, '-> accepted (unexpected)'); }
  catch (e) { console.log(name.padEnd(15), '->', 'rejected:', e.message); }
}

valid token      -> https://pocket-coffee.myshopify.com
expired         -> rejected: token expired (exp)
wrong audience  -> rejected: audience is not this app (aud)
host mismatch   -> rejected: iss and dest hosts differ
wrong secret    -> rejected: bad signature

curl -X POST "https://${SHOP}.myshopify.com/admin/oauth/access_token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  -d "subject_token=${ID_TOKEN}" \
  -d 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
  -d "client_id=${SHOPIFY_CLIENT_ID}" \
  -d "client_secret=${SHOPIFY_CLIENT_SECRET}" \
  -d 'expiring=1'

// app/routes/app._index.tsx
import type { LoaderFunctionArgs } from "react-router";
import { authenticate } from "../shopify.server";

export async function loader({ request }: LoaderFunctionArgs) {
  const { admin } = await authenticate.admin(request);

  const response = await admin.graphql(`
    query {
      shop {
        name
      }
    }
  `);

  return await response.json();
}

// app/shopify.server.ts (excerpt of the public template)
const shopify = shopifyApp({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET || "",
  apiVersion: ApiVersion.October26,
  scopes: process.env.SCOPES?.split(","),
  appUrl: process.env.SHOPIFY_APP_URL || "",
  authPathPrefix: "/auth",
  sessionStorage: new PrismaSessionStorage(prisma),
  distribution: AppDistribution.AppStore,
  future: {
    expiringOfflineAccessTokens: true,
  },
});

// token-client.mjs
const TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
const ID_TOKEN = 'urn:ietf:params:oauth:token-type:id_token';
const OFFLINE = 'urn:shopify:params:oauth:token-type:offline-access-token';
const ONLINE = 'urn:shopify:params:oauth:token-type:online-access-token';

async function post(origin, params) {
  const res = await fetch(`${origin}/admin/oauth/access_token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
    body: new URLSearchParams(params),
    signal: AbortSignal.timeout(30_000),
  });
  return { status: res.status, body: await res.json().catch(() => ({})) };
}

export function exchangeIdToken(origin, { clientId, clientSecret, idToken, online = false, expiring = true }) {
  const p = {
    client_id: clientId,
    client_secret: clientSecret,
    grant_type: TOKEN_EXCHANGE,
    subject_token: idToken,
    subject_token_type: ID_TOKEN,
    requested_token_type: online ? ONLINE : OFFLINE,
  };
  if (!online && expiring) p.expiring = '1';
  return post(origin, p);
}

export function refresh(origin, { clientId, clientSecret, refreshToken }) {
  return post(origin, {
    client_id: clientId,
    client_secret: clientSecret,
    grant_type: 'refresh_token',
    refresh_token: refreshToken,
  });
}

export function clientCredentials(origin, { clientId, clientSecret }) {
  return post(origin, { client_id: clientId, client_secret: clientSecret, grant_type: 'client_credentials' });
}

// Keep the pair and absolute expiry times; never log the token values.
export function toRecord(body, now = Date.now()) {
  return {
    accessToken: body.access_token,
    refreshToken: body.refresh_token ?? null,
    scope: body.scope,
    accessExpiresAt: body.expires_in > 0 ? now + body.expires_in * 1000 : null,
    refreshExpiresAt: body.refresh_token_expires_in > 0 ? now + body.refresh_token_expires_in * 1000 : null,
  };
}

// Returns a usable record, refreshing 60 seconds before expiry.
// 401 from the refresh endpoint is final: the merchant must reopen the app (token exchange).
export async function ensureFresh(origin, creds, record, now = Date.now()) {
  if (record.accessExpiresAt === null || record.accessExpiresAt - now > 60_000) return { record, action: 'none' };
  const r = await refresh(origin, { ...creds, refreshToken: record.refreshToken });
  if (r.status === 401) return { record: null, action: 're-authenticate' };
  if (r.status === 429 || r.status >= 500) return { record, action: 'retry-later' };
  if (r.status !== 200) throw new Error(`refresh failed: ${r.status}`);
  return { record: toRecord(r.body, now), action: 'refreshed' };
}

// mock-shopify.mjs
import http from 'node:http';
import { validateIdToken } from './id-token.mjs';

export function startMock({ clientId, clientSecret }) {
  let n = 0;
  const live = new Set(); // refresh tokens that are still usable
  const server = http.createServer(async (req, res) => {
    let raw = '';
    for await (const c of req) raw += c;
    const f = Object.fromEntries(new URLSearchParams(raw));
    const send = (code, obj) => { res.writeHead(code, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(obj)); };
    if (req.url !== '/admin/oauth/access_token' || req.method !== 'POST') return send(404, {});
    if (f.client_id !== clientId || f.client_secret !== clientSecret) return send(401, { error: 'invalid_client' });
    const pair = () => { const rt = `refresh-${++n}`; live.add(rt); return {
      access_token: `access-${n}`, scope: 'read_products,write_products', expires_in: 3600,
      refresh_token: rt, refresh_token_expires_in: 7776000 }; };
    if (f.grant_type === 'urn:ietf:params:oauth:grant-type:token-exchange') {
      try { validateIdToken(f.subject_token, { clientId, clientSecret }); } catch { return send(400, { error: 'invalid_subject_token' }); }
      if (f.requested_token_type.endsWith('online-access-token')) {
        return send(200, { access_token: `online-${++n}`, scope: 'read_products,write_products', expires_in: 86399,
          associated_user_scope: 'read_products', associated_user: { id: 42, account_owner: false, email_verified: true } });
      }
      return f.expiring === '1' ? send(200, pair())
        : send(200, { access_token: `legacy-${++n}`, scope: 'read_products,write_products' });
    }
    if (f.grant_type === 'refresh_token') {
      if (!live.delete(f.refresh_token)) return send(401, { error: 'invalid_request', error_description: 'This request requires an active refresh_token' });
      return send(200, pair());
    }
    if (f.grant_type === 'client_credentials') return send(200, { access_token: `cc-${++n}`, scope: 'read_products', expires_in: 86399 });
    send(400, { error: 'unsupported_grant_type' });
  });
  return new Promise((r) => server.listen(0, '127.0.0.1', () => r({ server, origin: `http://127.0.0.1:${server.address().port}` })));
}

// token-demo.mjs
import { startMock } from './mock-shopify.mjs';
import { signIdToken, sampleClaims } from './id-token.mjs';
import { exchangeIdToken, refresh, clientCredentials, toRecord, ensureFresh } from './token-client.mjs';

const creds = { clientId: '00000000000000000000000000000000', clientSecret: 'placeholder-client-secret-not-real' };
const { server, origin } = await startMock(creds);
const idToken = signIdToken(sampleClaims(creds.clientId), creds.clientSecret);
const show = (label, r) => console.log(label.padEnd(34), r.status, Object.keys(r.body).join(','));

const off = await exchangeIdToken(origin, { ...creds, idToken });
show('exchange offline expiring=1', off);
show('exchange online', await exchangeIdToken(origin, { ...creds, idToken, online: true }));
show('exchange offline expiring=0', await exchangeIdToken(origin, { ...creds, idToken, expiring: false }));
show('exchange with bad ID token', await exchangeIdToken(origin, { ...creds, idToken: 'x.y.z' }));
show('client credentials', await clientCredentials(origin, creds));

const rec = toRecord(off.body);
const t0 = Date.now();
console.log('fresh record, 1 h left       ->', (await ensureFresh(origin, creds, rec, t0)).action);
const late = t0 + 3600_000 - 30_000; // 30 s before expiry
console.log('30 s before expiry           ->', (await ensureFresh(origin, creds, rec, late)).action);
const bogus = { ...rec, refreshToken: 'refresh-that-was-revoked' };
const dead = await refresh(origin, { ...creds, refreshToken: bogus.refreshToken });
console.log('unknown or revoked refresh   ->', dead.status, dead.body.error);
console.log('ensureFresh on that record   ->', (await ensureFresh(origin, creds, bogus, late)).action);
server.close();

exchange offline expiring=1        200 access_token,scope,expires_in,refresh_token,refresh_token_expires_in
exchange online                    200 access_token,scope,expires_in,associated_user_scope,associated_user
exchange offline expiring=0        200 access_token,scope
exchange with bad ID token         400 error
client credentials                 200 access_token,scope,expires_in
fresh record, 1 h left       -> none
30 s before expiry           -> refreshed
unknown or revoked refresh   -> 401 invalid_request
ensureFresh on that record   -> re-authenticate

curl -X POST "https://${SHOP}.myshopify.com/admin/oauth/access_token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  -d "client_id=${SHOPIFY_CLIENT_ID}" \
  -d "client_secret=${SHOPIFY_CLIENT_SECRET}" \
  -d "subject_token=${NON_EXPIRING_OFFLINE_TOKEN}" \
  -d 'subject_token_type=urn:shopify:params:oauth:token-type:offline-access-token' \
  -d 'requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token' \
  -d 'expiring=1'

query GrantedScopes {
  currentAppInstallation {
    accessScopes {
      handle
      description
    }
  }
}

// server side (React Router template)
const { scopes } = await authenticate.admin(request);
await scopes.request(['read_customers']);

// client side (App Bridge)
shopify.scopes.request(['read_customers']);

https://admin.shopify.com/store/<store-name>/oauth/install?client_id=<client-id>&optional_scopes=read_customers

mutation RevokeScopes {
  appRevokeAccessScopes(scopes: ["read_customers"]) {
    revoked {
      handle
    }
    userErrors {
      field
      message
    }
  }
}

// granted-scopes.mjs
const declared = { required: 'write_products,read_inventory,read_orders,read_locales'.split(','), optional: ['read_customers', 'read_all_orders'] };
const implied = (h) => (h.startsWith('write_') ? ['write_' + h.slice(6), 'read_' + h.slice(6)] : [h]);
export function expand(handles) { return new Set(handles.flatMap(implied)); }
export function missing(granted, wanted) { const g = expand(granted); return wanted.filter((h) => !g.has(h)); }
const grantedFromApi = ['write_products', 'read_inventory', 'read_orders', 'read_locales']; // sample currentAppInstallation result
console.log('required but not granted:', missing(grantedFromApi, declared.required));
console.log('optional to request:', missing(grantedFromApi, declared.optional));
console.log('implicit read of write_products present:', expand(grantedFromApi).has('read_products'));

required but not granted: []
optional to request: [ 'read_customers', 'read_all_orders' ]
implicit read of write_products present: true

query CustomerContact($id: ID!) {
  customer(id: $id) {
    id
    email
    firstName
    lastName
    phone
  }
}