Shopify Expiring Token Management

2.2.1 Requirement

As of April 2026, Shopify mandates that all OAuth apps use expiring offline access tokens with rotation. Non-expiring tokens return 403: Non-expiring access tokens are no longer accepted for the Admin API. This affects every Shopify Admin API call made by CRM Sync — customer sync, product queries, order lookups, webhook registration, and storefront token provisioning.

What Changed

Compliance Flag

The Shopify app must declare expiring token support:

// app/shopify.server.ts
shopifyApp({
  // ...
  future: {
    expiringOfflineAccessTokens: true,
  },
});

The OAuth token exchange must include expiring: "1":

POST https://{shop}/admin/oauth/access_token
Content-Type: application/x-www-form-urlencoded

client_id={id}&client_secret={secret}&code={code}&expiring=1

2.2.2 Architecture

Token Lifecycle

Install / Re-install OAuth
        │
        ▼
POST /admin/oauth/access_token  (code + expiring=1)
        │
        ▼
┌─────────────────────────────────────┐
│  access_token   (shpua_..., ~24h)   │
│  refresh_token  (one-time use)      │
│  expires_in     (seconds)           │
└──────────────┬──────────────────────┘
               │
               ▼
        KV Store (CRM_STATE)
        ├── shopify_admin_token
        ├── shopify_refresh_token
        └── shopify_token_expires_at (ISO timestamp)
               │
               │  Before expiry (5-min buffer)
               ▼
POST /admin/oauth/access_token  (grant_type=refresh_token)
        │
        ▼
┌─────────────────────────────────────┐
│  NEW access_token                   │
│  NEW refresh_token  (old one dies)  │
│  NEW expires_in                     │
└─────────────────────────────────────┘

Three Token Surfaces

Multi-Tenant Token Storage

Each tenant's tokens are stored independently in KV under tenant:{shop}:

{
  "shopify_admin_token": "shpua_...",
  "shopify_refresh_token": "shprf_...",
  "shopify_token_expires_at": "2026-05-21T19:00:00.000Z",
  "shopify_store_domain": "hx-stage.myshopify.com",
  "shopify_app_secret": "..."
}

The cron iterates all registered tenants and refreshes each independently.

2.2.3 Implementation Reference

Core Refresh Function

workers/crm-sync/src/index.ts — refreshShopifyTokenIfNeeded()

• Reads tenant config from KV
• Skips if no refresh_token or token_expires_at stored
• Skips if more than 5 minutes remain before expiry (unless force=true)
• Calls POST https://{shop}/admin/oauth/access_token with grant_type=refresh_token
• Saves new access_token, refresh_token, and computed expires_at back to KV
• Updates in-memory cfg.shopifyAdminToken for the current request

Where Refresh Is Called

OAuth Install Flow

/admin/shopify-install → redirect to Shopify OAuth → /admin/shopify-callback

The callback handler:

1. Exchanges authorization code for tokens with expiring: "1"
2. Stores access_token, refresh_token, expires_at in tenant KV
3. Registers the tenant via registerTenant()
4. Auto-registers CUSTOMERS_CREATE and CUSTOMERS_UPDATE webhooks

Shopify App Session Sync

app/routes/app.tsx loader:

1. Authenticates the admin session via shopify.authenticate.admin()
2. Sends session.accessToken to CRM worker via POST /config?shop=
3. Provisions a Storefront API token via Admin API if not already present
4. The CRM worker maps shopify_access_token → shopify_admin_token

This ensures the CRM worker always has a fresh token when the merchant opens the app, even if the cron-refreshed token has expired.

2.2.4 Required Scopes

Declared in shopify.app.crm-sync.toml under [access_scopes]:

Scopes in the TOML must match the OAuth install URL request. Shopify silently drops undeclared scopes. Deploy scope changes with:

npx shopify app deploy --config=shopify.app.crm-sync.toml

2.2.5 Diagnostics

Settings Page Indicators

The /settings admin page shows:

• Token Type: OAuth (expiring) for shpua_ prefix, Admin API for shpat_ (legacy)
• Refresh Token: Present or None
• Expires: ISO timestamp with countdown
• API Health: Tests GET /admin/api/2026-04/shop.json with current token

Manual Actions

Common Failures

2.2.6 Operational Checklist

• [ ] shopify.server.ts has expiringOfflineAccessTokens: true
• [ ] OAuth token exchange includes expiring: "1" parameter
• [ ] shopify_app_secret is stored in tenant KV config
• [ ] Cron trigger */15 * * * * is active in wrangler.toml
• [ ] Settings page shows token type OAuth (expiring) with refresh token present
• [ ] shopify.app.crm-sync.toml declares all required scopes
• [ ] App deployed after scope changes: npx shopify app deploy --config=shopify.app.crm-sync.toml