Begin the OAuth flow by redirecting the merchant to Shopify's authorization endpoint with parameters: `client_id`, `scope`, `redirect_uri`, and a cryptographically random `state` value stored in a cookie or session.
Shopify redirects back to your `redirect_uri` with a `code` and `shop` parameter; validate that `state` matches, that `shop` ends in `.myshopify.com`, and verify the `hmac` parameter by recomputing it over the sorted query parameters using your client secret.
Exchange the `code` for an access token by POSTing to `https://{shop}/admin/oauth/access_token` with `client_id`, `client_secret`, and `code`; store the returned `access_token` securely associated with the shop.
For embedded apps using Shopify App Bridge, retrieve session tokens from App Bridge's `getSessionToken()` method (a signed JWT) and send them to your backend on each request instead of relying on cookies.
On your backend, verify the session token JWT signature using your app's client secret and validate the `iss`, `dest`, `aud`, and `exp` claims.
Use online tokens (associated with a specific staff user) for embedded app requests and offline tokens (shop-level, long-lived) for background jobs and webhooks.
Known gotchas
Session tokens expire after 60 seconds — your frontend must call `getSessionToken()` fresh before each authenticated API request, not cache it.
Third-party cookie blocking in browsers means you cannot rely on cookies for authentication inside the Shopify admin iframe — session tokens are the required replacement.
The `hmac` validation on the OAuth callback must exclude the `hmac` parameter itself from the sorted query string before hashing.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp