API Authentication

The LaunchMyStore API uses OAuth 2.0 for authentication. This page covers the authentication methods available and how to use them in your API requests.

Authentication Methods

Access Tokens

OAuth 2.0 access tokens for server-to-server API calls

Session Tokens

JWTs for embedded app API calls

Access Tokens

Access tokens are obtained through the OAuth 2.0 flow and used for server-to-server API calls.

Obtaining Access Tokens

Your app receives its authorization code through the managed install handoff: when a merchant installs (or reinstalls) your app, LaunchMyStore redirects their browser to your /auth endpoint with code, state, and an HMAC signature. Do not redirect merchants to GET /apps/oauth/authorize yourself — that endpoint is a merchant-authenticated JSON API used by the LaunchMyStore admin, and a top-level browser redirect returns 401.

// Inside your /auth handler (after HMAC verification):
// exchange the handoff code for tokens
const tokenResponse = await fetch('https://api.launchmystore.io/apps/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    code: req.query.code,       // from the /auth handoff
    grant_type: 'authorization_code',
    state: req.query.state      // echo the handoff state verbatim
  })
});

// The token payload is wrapped in the platform envelope — read `data`
const { data } = await tokenResponse.json();
const { access_token, refresh_token, expires_in } = data;

Using Access Tokens

Include the access token in the Authorization header:

curl -X GET "https://api.launchmystore.io/api/v1/products.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.launchmystore.io/api/v1/products.json', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

Token Expiration

Access tokens expire after 24 hours. Use the refresh token to get a new access token:

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://api.launchmystore.io/apps/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: refreshToken,
      grant_type: 'refresh_token'
    })
  });
  
  const { data } = await response.json();   // envelope: { status, state, data }
  
  // Store new tokens
  await storeTokens(data.access_token, data.refresh_token);
  
  return data.access_token;
}

Refresh tokens expire after 30 days. If a refresh token expires, the merchant must re-authorize your app.

Token Management

Implement a token manager for automatic refresh:

class TokenManager {
  constructor(shopId) {
    this.shopId = shopId;
  }
  
  async getAccessToken() {
    const tokens = await this.loadTokens();
    
    // Check if access token is expired (with 5 min buffer)
    if (tokens.expiresAt < Date.now() + 300000) {
      return this.refreshToken(tokens.refreshToken);
    }
    
    return tokens.accessToken;
  }
  
  async refreshToken(refreshToken) {
    try {
      const response = await fetch('https://api.launchmystore.io/apps/oauth/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          client_id: process.env.APP_CLIENT_ID,
          client_secret: process.env.APP_CLIENT_SECRET,
          refresh_token: refreshToken,
          grant_type: 'refresh_token'
        })
      });
      
      if (!response.ok) {
        throw new Error('Token refresh failed');
      }
      
      const { data } = await response.json();   // unwrap the envelope
      
      await this.storeTokens({
        accessToken: data.access_token,
        refreshToken: data.refresh_token,
        expiresAt: Date.now() + (data.expires_in * 1000)
      });
      
      return data.access_token;
    } catch (error) {
      // Refresh token may be expired - need re-authorization
      await this.markNeedsReauth();
      throw error;
    }
  }
  
  async loadTokens() {
    // Load from database
    return db.tokens.findOne({ shopId: this.shopId });
  }
  
  async storeTokens(tokens) {
    await db.tokens.updateOne(
      { shopId: this.shopId },
      { $set: tokens },
      { upsert: true }
    );
  }
  
  async markNeedsReauth() {
    await db.shops.updateOne(
      { id: this.shopId },
      { $set: { needsReauth: true } }
    );
  }
}

Session Tokens

Session tokens are JWTs used for embedded app API calls. They’re obtained through App Bridge.

Getting Session Tokens

import { createApp } from '@launchmystore/app-bridge';

const app = createApp({
  apiKey: 'your-client-id',
  host: new URLSearchParams(location.search).get('host')
});

const token = await app.getSessionToken();

Using Session Tokens

Include in the Authorization header:

const token = await app.getSessionToken();

const response = await fetch('https://your-app.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Verifying Session Tokens

Verify session tokens on your backend:

import jwt from 'jsonwebtoken';

function verifySessionToken(token) {
  try {
    const decoded = jwt.verify(token, process.env.APP_CLIENT_SECRET, {
      algorithms: ['HS256'],
      audience: process.env.APP_CLIENT_ID,
      issuer: 'https://launchmystore.io'
    });
    
    return {
      valid: true,
      shopId: decoded.sub,
      shopDomain: decoded.dest
    };
  } catch (error) {
    return { valid: false, error: error.message };
  }
}

See Session Tokens for detailed documentation.

Scopes

Request only the scopes your app needs:

Store Data Scopes

Scope	Access
`read_shop`	View store information
`write_shop`	Modify store settings
`read_products`	View products and variants
`write_products`	Create, update, delete products
`read_collections`	Reserved — unused. Collection reads are gated by `read_products`.
`write_collections`	Reserved — unused. Collection writes are gated by `write_products`.
`read_inventory`	View inventory levels
`write_inventory`	Adjust inventory

Order Scopes

Scope	Access
`read_orders`	View orders and transactions, and fulfillments
`write_orders`	Create, update, fulfill orders and manage fulfillments
`read_fulfillments`	Reserved — unused. Fulfillment reads are gated by `read_orders`.
`write_fulfillments`	Reserved — unused. Fulfillment writes are gated by `write_orders`.

Customer Scopes

Scope	Access
`read_customers`	View customer data
`write_customers`	Create, update customers

Content Scopes

Scope	Access
`read_content`	View pages, blogs, articles
`write_content`	Manage pages, blogs, articles
`read_themes`	View theme files
`write_themes`	Modify theme files
`read_metafields`	View metafield data
`write_metafields`	Create, update metafields
`read_files`	View files in the store asset library
`write_files`	Upload and delete files in the asset library

Admin Scopes

Scope	Access
`read_discounts`	View discount codes
`write_discounts`	Manage discounts
`read_gift_cards`	View gift cards
`write_gift_cards`	Manage gift cards
`read_shipping`	View shipping zones (full)
`write_shipping`	Manage shipping zones (full)

Billing & Analytics Scopes

Scope	Access
`read_billing`	View merchant plan, subscriptions, invoices, credits
`write_billing`	Reserved — future support for managing payment methods
`read_analytics`	View store analytics (summary, sales, top products)

Settings & Marketing Scopes

Scope	Access
`read_settings`	View general store settings, shipping, payment, tax rules
`write_settings`	Update a whitelisted subset of general store settings
`read_marketing`	Reserved — future read access to campaigns and automations
`write_marketing`	Reserved — future write access to campaigns and automations
`read_email_templates`	View transactional email templates
`write_email_templates`	Create and modify transactional email templates

Rate Limits

API requests are rate limited based on your app’s billing tier:

Tier	Requests/Second
Free	20
Basic	40
Pro	100
Enterprise	500

The limit is a flat per-second sliding window per (app, store); there is no separate burst allowance.

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 40
X-RateLimit-Remaining: 38
X-RateLimit-Reset: 1705312800

Handling Rate Limits

async function apiCall(url, options, retries = 3) {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
    if (retries > 0) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitMs = (resetTime * 1000) - Date.now() + 100;
      
      await sleep(Math.min(waitMs, 60000));
      return apiCall(url, options, retries - 1);
    }
    
    throw new Error('Rate limit exceeded');
  }
  
  return response;
}

Error Responses

Authentication Errors

Status	Description
401	Missing, invalid, or expired access token (also returned when the app has been uninstalled and its token cleared).
403	The installation is missing a scope the endpoint requires.

There is no machine-readable code string — branch on the HTTP status. The message is carried in errors.base[0].

Error Response Format

Errors use the standard { errors } body:

{
  "errors": {
    "base": ["Invalid or expired access token"]
  }
}

Handling Errors

async function makeApiRequest(endpoint, options = {}) {
  const response = await fetch(
    `https://api.launchmystore.io/api/v1${endpoint}`,
    {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${await tokenManager.getAccessToken()}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    const message = body?.errors?.base?.[0] || 'Request failed';

    switch (response.status) {
      case 401:
        // Token invalid/expired (or app uninstalled) — refresh and retry once
        await tokenManager.refreshToken();
        return makeApiRequest(endpoint, options);

      case 403:
        throw new Error(`Insufficient permissions: ${message}`);

      default:
        throw new Error(message);
    }
  }

  return response.json();
}

Security Best Practices

Never expose secrets

Never include your client secret in client-side code. Keep it on your backend only.

Use HTTPS everywhere

Always use HTTPS for API calls and webhook endpoints.

Validate the state parameter

Always validate the state parameter in OAuth callbacks to prevent CSRF attacks.

Store tokens securely

Encrypt access and refresh tokens in your database. Never log them.

Request minimal scopes

Only request the scopes your app actually needs. Merchants trust apps with fewer permissions.

Handle token revocation

Tokens can be revoked if a merchant uninstalls your app. Handle this gracefully.

Testing Authentication

Test Mode

Use test credentials for development:

const config = {
  clientId: process.env.NODE_ENV === 'production'
    ? process.env.APP_CLIENT_ID
    : process.env.APP_TEST_CLIENT_ID,
  clientSecret: process.env.NODE_ENV === 'production'
    ? process.env.APP_CLIENT_SECRET
    : process.env.APP_TEST_CLIENT_SECRET
};

Mock Tokens

For unit testing, create mock tokens:

import jwt from 'jsonwebtoken';

function createMockSessionToken(payload = {}) {
  return jwt.sign(
    {
      iss: 'https://launchmystore.io',
      aud: 'test-client-id',
      sub: 'test-shop-id',
      dest: 'https://test-store.launchmystore.io',
      exp: Math.floor(Date.now() / 1000) + 86400,
      iat: Math.floor(Date.now() / 1000),
      ...payload
    },
    'test-client-secret',
    { algorithm: 'HS256' }
  );
}

​API Authentication

​Authentication Methods

Access Tokens

Session Tokens

​Access Tokens

​Obtaining Access Tokens

​Using Access Tokens

​Token Expiration

​Token Management

​Session Tokens

​Getting Session Tokens

​Using Session Tokens

​Verifying Session Tokens

​Scopes

​Store Data Scopes

​Order Scopes

​Customer Scopes

​Content Scopes

​Admin Scopes

​Billing & Analytics Scopes

​Settings & Marketing Scopes

​Rate Limits

​Rate Limit Headers

​Handling Rate Limits

​Error Responses

​Authentication Errors

​Error Response Format

​Handling Errors

​Security Best Practices

​Testing Authentication

​Test Mode

​Mock Tokens

​See Also

API Authentication

Authentication Methods

Access Tokens

Obtaining Access Tokens

Using Access Tokens

Token Expiration

Token Management

Session Tokens

Getting Session Tokens

Using Session Tokens

Verifying Session Tokens

Scopes

Store Data Scopes

Order Scopes

Customer Scopes

Content Scopes

Admin Scopes

Billing & Analytics Scopes

Settings & Marketing Scopes

Rate Limits

Rate Limit Headers

Handling Rate Limits

Error Responses

Authentication Errors

Error Response Format

Handling Errors

Security Best Practices

Testing Authentication

Test Mode

Mock Tokens

See Also