How to Connect to the Shopify Admin API for the First Time

Connecting to the Shopify Admin API is the first step to building apps that read or manage store data. This guide walks you through the two common connection models (OAuth for public apps and a store-level custom app), how to obtain credentials, exchanging tokens, making GraphQL and REST requests, and important production considerations.

Prerequisites

• A Shopify store you control (development or partner store).
• A Shopify Partner account if you plan to build a public app.
• Node.js (examples use Express and node-fetch/axios) or any HTTP client.
• Familiarity with HTTP headers and JSON.

Two ways to connect

• Public app (OAuth): Use the OAuth 2.0 install flow so any merchant can install your app. You must request scopes and exchange a temporary code for a permanent access token.
• Store-level custom app: Created directly in a store’s admin (“Develop apps”). You can generate API credentials and an access token immediately — useful for one-off integrations or internal tooling.

Both approaches use the same Admin API endpoints; the difference is how you obtain the access token.

Create an app and get credentials

• Public apps: Create your app in the Shopify Partner Dashboard. You will get an API key (client id) and API secret (client secret). Configure app URLs (redirect URI for OAuth) and requested scopes.
• Custom (store) apps: In the store Admin, go to Apps -> Develop apps -> Create an app. Then “Configure Admin API scopes” and “Install app” to generate an Admin API access token.

Shopify Admin API base endpoints (versioned):

• REST: https://{shop}.myshopify.com/admin/api/{version}/
• GraphQL: https://{shop}.myshopify.com/admin/api/{version}/graphql.json

Replace {shop} with shop domain (example-shop.myshopify.com) and {version} with a supported API version (for example, 2025-01). Always use a specific version to avoid breaking changes.

OAuth install flow (public apps)

The OAuth flow for public apps looks like this:

1. Redirect merchant to Shopify install URL.
2. Merchant approves scopes and installs the app.
3. Shopify redirects back to your app with a temporary code.
4. Exchange the code for a permanent access token.

Build the install URL

Example install URL format:

https://{shop}.myshopify.com/admin/oauth/authorize?client id=\<APP API KEY\>&scope=read products,write products&redirect uri=\URI\>&state=\<RANDOM STATE\>

• client_id: your app API key
• scope: comma-separated scopes you request
• redirect_uri: must match the app’s configured redirect URI
• state: random string for CSRF protection

Exchange code for token (curl)

Here’s the token exchange call Shopify expects after the merchant approves the app:

curl -X POST "https://{shop}.myshopify.com/admin/oauth/access_token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"\<APP_API_KEY\", "client_secret":"\<APP_API_SECRET\", "code":"\<AUTHORIZATION_CODE\"}’'

Successful response example:

{ "access_token": "shpca_abc123...", "scope": "read_products,write_products" }

Quick Node/Express callback example (exchange code)

const express = require('express');
const fetch = require('node-fetch');
const app = express();

app.get('/auth/callback', async (req, res) => {
  const { code, shop, state } = req.query;
  // validate state here

  const tokenResp = await fetch(`https://\${shop}/admin/oauth/access_token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: '\<APP_API_KEY\>',
      client_secret: '\<APP_API_SECRET\>',
      code
    })
  });

  const tokenJson = await tokenResp.json();
  const accessToken = tokenJson.access_token;

  // Persist accessToken and shop to your DB
  res.send('App installed');
});

app.listen(3000);

Note: In code blocks above the characters “\<” and “\>” are escaped placeholders. Replace them with your real values.

Custom (store) app flow

If you create a custom app from a store’s admin, Shopify generates an access token for you after installing the app. You do not need an OAuth flow. Use the token directly in requests.

Steps:

1. Admin -> Apps -> Develop apps -> Create app
2. Configure scopes
3. Install app -> Reveal Admin API access token
4. Use token with X-Shopify-Access-Token header

Making requests — GraphQL and REST examples

GraphQL example (javascript)

// GraphQL POST to the shop's GraphQL endpoint
const fetch = require('node-fetch');

const SHOP = 'example-shop.myshopify.com';
const ACCESS_TOKEN = 'shpca_...';

const query = `query getShop { shop { name myshopifyDomain } }`;

const res = await fetch(`https://\${SHOP}/admin/api/2025-01/graphql.json`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Shopify-Access-Token': ACCESS_TOKEN
  },
  body: JSON.stringify({ query })
});

const data = await res.json();
console.log(data);

REST example (curl)

curl -X GET "https://{shop}.myshopify.com/admin/api/2025-01/products.json" \
  -H "X-Shopify-Access-Token: shpca_..."

Using the Admin API header

Always include the access token in the X-Shopify-Access-Token header for Admin API requests. For public apps, store the token you received from the OAuth exchange. For custom apps, use the generated token.

Handling scopes, versioning, and webhooks

• Request only the scopes your app needs. Merchants see the scopes during install.
• Shopify API versions are released quarterly. Locking to a specific version keeps behavior stable. Update your app for new versions before older ones are removed.
• Use webhooks to receive real-time notifications (orders, products, app/uninstall). Validate webhook HMAC signatures using your app secret.

Security and production checklist

• Always use HTTPS for redirects and endpoints.
• Validate the OAuth state parameter to prevent CSRF.
• Verify HMAC signatures on OAuth callback requests for additional safety.
• Store access tokens encrypted at rest. Limit DB access to those secrets.
• Rotate credentials if they leak and provide a revoke flow.
• Limit requested scopes to the minimum required.
• Implement rate limit handling: Shopify returns X-Shopify-Shop-Api-Call-Limit headers. Back off and retry with exponential backoff when you near limits.

Troubleshooting common errors

• 401 Unauthorized: Token missing/invalid. Ensure X-Shopify-Access-Token header is set correctly.
• 403 Forbidden: Requested an API scope you don’t have. Re-check requested scopes and merchant grant.
• 422 / malformed JSON: Check Content-Type and request body format.
• Redirect mismatch: OAuth redirect_uri must exactly match the app’s configured redirect URL.
• Webhook HMAC failure: Use your app secret to validate the HMAC on the request body.

Next steps & resources

• Use GraphQL Admin API for efficient bulk reads/writes; REST is fine for simpler tasks.
• Register your app with the Shopify Partner Dashboard if you intend to publish.
• Read Shopify’s official docs: Admin API reference, OAuth guide, and webhook verification.

Connecting to Shopify for the first time is mostly about getting the authentication step right. Once you have a valid access token and understand versioning and scopes, the Admin API behaves like any other HTTP JSON API.