Shopify Install & Auth

Overview

Set up Shopify app authentication using the official @shopify/shopify-api library. Covers OAuth flow, session token exchange, custom app tokens, and Storefront API access.

Prerequisites

Node.js 18+ (the @shopify/shopify-api v9+ requires it)
A Shopify Partner account at https://partners.shopify.com
An app created in the Partner Dashboard with API credentials
A development store for testing

Instructions

Step 1: Install the Shopify API Library

# Core library + Node.js runtime adapter
npm install @shopify/shopify-api @shopify/shopify-app-remix
# Or for standalone Node apps:
npm install @shopify/shopify-api @shopify/shopify-app-express

# For Remix (recommended by Shopify):
npm install @shopify/shopify-app-remix @shopify/app-bridge-react

Step 2: Configure Environment Variables

Create a .env file (add to .gitignore immediately):

# .env — NEVER commit this file
SHOPIFY_API_KEY=your_app_api_key
SHOPIFY_API_SECRET=your_app_api_secret
SHOPIFY_SCOPES=read_products,write_products,read_orders,write_orders
SHOPIFY_APP_URL=https://your-app.example.com
SHOPIFY_HOST_NAME=your-app.example.com

# For custom/private apps only:
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx

# API version — use a stable quarterly release
# Update quarterly — see shopify.dev/docs/api/usage/versioning
SHOPIFY_API_VERSION=2025-04

# .gitignore — add these immediately
.env
.env.local
.env.*.local

Step 3: Initialize the Shopify API Library

// src/shopify.ts
import "@shopify/shopify-api/adapters/node";
import { shopifyApi, LATEST_API_VERSION, Session } from "@shopify/shopify-api";

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  scopes: process.env.SHOPIFY_SCOPES!.split(","),
  hostName: process.env.SHOPIFY_HOST_NAME!,
  apiVersion: LATEST_API_VERSION,
  isEmbeddedApp: true,
});

export default shopify;

Step 4: Implement OAuth Flow (Public Apps)

Express-based OAuth flow that redirects to Shopify and handles the callback token exchange.

See OAuth Flow for the complete Express route implementation.

Step 5: Token Exchange (Embedded Apps)

For embedded apps, use session token exchange instead of traditional OAuth:

// Token exchange — converts session token (JWT) to API access token
import shopify from "../shopify";

async function exchangeToken(
  shop: string,
  sessionToken: string
): Promise<Session> {
  const { session } = await shopify.auth.tokenExchange({
    sessionToken,
    shop,
    requestedTokenType: RequestedTokenType.OfflineAccessToken,
  });
  return session;
}

Step 6: Custom App / Private App Auth

For custom apps installed on a single store, use a permanent access token with no OAuth needed.

See Custom App Auth for the complete setup.

Step 7: Verify Auth is Working

// Quick connectivity test
async function verifyShopifyAuth(session: Session): Promise<void> {
  const client = new shopify.clients.Graphql({ session });

  const response = await client.request(`{
    shop {
      name
      email
      plan {
        displayName
      }
      primaryDomain {
        url
      }
    }
  }`);

  console.log("Connected to:", response.data.shop.name);
  console.log("Plan:", response.data.shop.plan.displayName);
  console.log("Domain:", response.data.shop.primaryDomain.url);
}

Output

@shopify/shopify-api installed and configured
OAuth flow or custom app auth operational
Session with valid access token persisted
Verified connection to the Shopify Admin API

Error Handling

Error	Cause	Solution
`InvalidApiKeyError`	Wrong `SHOPIFY_API_KEY`	Verify in Partner Dashboard > App > API credentials
`InvalidHmacError` during callback	Secret mismatch or URL tampering	Check `SHOPIFY_API_SECRET` matches Partner Dashboard
`SessionNotFound`	Session not persisted	Implement `SessionStorage` (DB, Redis, or file)
`HttpResponseError: 401`	Token expired or revoked	Merchant uninstalled app — trigger re-auth
`InvalidScopeError`	Requested scope not approved	Only use scopes from the approved list in your app config
`ShopifyErrors.InvalidShop`	Malformed shop domain	Must be `*.myshopify.com` — use `sanitizeShop()`

Examples

Shopify API Access Scopes Reference

Scope	Grants Access To
`read_products` / `write_products`	Products, variants, collections, images
`read_orders` / `write_orders`	Orders, transactions, fulfillments
`read_customers` / `write_customers`	Customer data, addresses, metafields
`read_inventory` / `write_inventory`	Inventory levels across locations
`read_content` / `write_content`	Pages, blogs, articles
`read_themes` / `write_themes`	Theme files and assets
`read_shipping` / `write_shipping`	Shipping zones, carrier services
`read_fulfillments` / `write_fulfillments`	Fulfillment orders and services

Storefront API Access

The Storefront API uses a separate token with its own higher rate limits.

See Storefront API Access for the complete client setup.

shopify-install-auth