OAuth 2.0 Authentication

LaunchMyStore uses OAuth 2.0 for secure app authentication. This allows merchants to grant your app specific permissions without sharing their credentials.

Two install paths

Depending on how the merchant reaches your app, one of two OAuth flows runs.

A. Managed install — the merchant clicks Install in our marketplace

The merchant sees the consent screen inside LaunchMyStore’s admin, approves the scopes, and we redirect them straight to your /auth endpoint with a pre-authorized code. You do not call /oauth/authorize in this flow — the consent already happened. See Install handoff (/auth) for the full contract: HMAC verification, exchange semantics, code samples in Node/Python/Ruby.

B. Re-authorization — your app needs a fresh grant later

When your app needs a fresh grant after install (lost tokens, expired refresh token, or a scope upgrade), redirect the merchant’s browser to the admin consent page:

https://app.launchmystore.io/oauth/authorize
  ?client_id=lms_app_xxxxxxxxxxxx
  &redirect_uri=https://your-app.com/auth/callback   # must be registered on your app
  &scope=read_products,write_products                # optional — defaults to registered scopes
  &state=<your own anti-CSRF nonce>                  # optional, echoed back as client_state
  &code_challenge=...&code_challenge_method=S256     # optional PKCE

The merchant logs in (if needed), reviews your app’s name, developer and requested scopes on the consent screen, and clicks Authorize. The browser is then redirected to your redirect_uri with:

Param	Meaning
`code`	Single-use authorization code (10-minute TTL).
`state`	Server-generated token — echo this exact value at `POST /apps/oauth/token`.
`client_state`	Your own `state` nonce, passed through verbatim (only if you sent one). Use it to bind the callback to the merchant’s session on your side.

If the merchant clicks Cancel you receive redirect_uri?error=access_denied&state=<your nonce>.

The consent page is app.launchmystore.io/oauth/authorize (the admin UI). The API endpoint api.launchmystore.io/apps/oauth/authorize is merchant-JWT-authenticated JSON that the consent page calls internally — redirecting a browser directly to the API returns 401. A merchant reinstall also re-runs the managed /auth handoff and delivers a fresh code, so either path recovers a lost token; prefer the consent redirect for scope upgrades (no uninstall involved).

Available Scopes

Request only the scopes your app needs. Merchants see all requested scopes during installation.

Store Data

Scope	Description
`read_shop`	View store information
`write_shop`	Modify store settings
`read_products`	View products and variants
`write_products`	Create, update, delete products
`read_collections`	View collections
`write_collections`	Manage collections

Orders & Customers

Scope	Description
`read_orders`	View orders and transactions
`write_orders`	Create, update, fulfill orders
`read_customers`	View customer data
`write_customers`	Create, update customers
`read_fulfillments`	View fulfillment data
`write_fulfillments`	Create, update fulfillments

Inventory & Discounts

Scope	Description
`read_inventory`	View inventory levels
`write_inventory`	Adjust inventory
`read_discounts`	View discount codes
`write_discounts`	Create, manage discounts

Metafields

Scope	Description
`read_metafields`	View metafield data
`write_metafields`	Create, update metafields

Content & Files

Scope	Description
`read_files`	List and download merchant-uploaded files (reserved — `/api/v1/files` endpoints not yet bound)
`write_files`	Upload, replace, delete files (reserved — `/api/v1/files` endpoints not yet bound)
`read_themes`	Read theme files and settings
`write_themes`	Install themes, edit theme files, toggle app embeds
`read_content`	View blogs, articles, pages
`write_content`	Create / update / delete blogs, articles, pages

Scopes marked reserved are declared in the OAuth catalog and can be requested by an app today, but the corresponding REST endpoints are not yet exposed under /api/v1/. Request them now if you want forward-compat; the API surface will land before the v1 freeze.

Shipping & Gift Cards

Scope	Description
`read_shipping`	View shipping zones, methods, and rates
`write_shipping`	Create / update / delete shipping zones and rates
`read_gift_cards`	View issued gift cards and balances
`write_gift_cards`	Issue, refund, or void gift cards

Billing, Analytics, Settings & Marketing

Scope	Description
`read_billing`	View merchant subscriptions and invoices
`write_billing`	Create one-time charges and recurring subscription products
`read_analytics`	Query the analytics / reports API
`read_settings`	View store-wide settings (taxes, payments, locale)
`write_settings`	Modify store-wide settings
`read_marketing`	View campaigns, segments, abandoned-cart data
`write_marketing`	Create / update marketing campaigns

Email Templates

Scope	Description
`read_email_templates`	Read transactional email templates registered by your app
`write_email_templates`	Override transactional email templates (order confirmation, password reset, etc.) — see Email Templates extension

Authorization Request

The authorize endpoint is a merchant-authenticated JSON API — it is called by the LaunchMyStore admin (with the merchant’s JWT), not by your app, and it does not redirect the browser:

GET https://api.launchmystore.io/apps/oauth/authorize
Authorization: Bearer <merchant admin JWT>

Your app receives the resulting code + state through the managed install handoff redirect to your /auth endpoint.

Parameters

Parameter	Required	Description
`client_id`	Yes	Your app’s Client ID
`scope`	Yes	Comma-separated list of scopes
`redirect_uri`	Yes	Your callback URL (must match registered URL)
`state`	Optional	Client-side nonce, stored server-side as `clientState`; not echoed back
`response_type`	Optional	Must be `code` (default)
`code_challenge`	Optional	PKCE (RFC 7636) challenge, 43-128 chars
`code_challenge_method`	Optional	`S256` (recommended) or `plain`

On success it returns JSON: { status, state: "success", data: { code, state, redirectUri, app } }. The server-generated data.state must be echoed back on the token exchange. See Authorize for the full contract.

Token Exchange

After the merchant approves, they’re redirected to your redirect_uri with a code parameter. Exchange this for tokens:

POST https://api.launchmystore.io/apps/oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "code": "authorization_code_from_callback",
  "grant_type": "authorization_code",
  "state": "state_from_callback"
}

Response

The token payload is wrapped in the standard platform envelope ({ status, state, message, data }) — read the fields from data:

{
  "status": 200,
  "state": "success",
  "message": null,
  "data": {
    "access_token": "lms_token_xxxxxxxxxxxxxxxxxxxxxxxx",
    "refresh_token": "lms_refresh_xxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "bearer",
    "expires_in": 86400,
    "scope": "read_products write_products read_orders"
  }
}

const { data } = await tokenResponse.json();
// data.access_token, data.refresh_token, data.scope ...

data.scope is a space-delimited string (e.g. "read_products write_orders") — split on a space, not a comma. This is the merchant’s granted scopes; persist it as your authorization source (see below). token_type is returned lowercase (bearer).

Token Refresh

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

POST https://api.launchmystore.io/apps/oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "refresh_token": "your_refresh_token",
  "grant_type": "refresh_token"
}

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

Refresh tokens rotate. Each refresh returns a new refresh_token and invalidates the one you just used. Always persist the newest refresh_token from the response and discard the old one — reusing a spent refresh token returns 401.

An expired access token does not require re-authorization or reinstalling the app — just call the refresh endpoint with a still-valid refresh token to get a new one.

Making Authenticated Requests

Include the access token in the Authorization header:

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

Security Best Practices

Store tokens securely

Never store tokens in client-side code or version control. Use encrypted database columns or a secrets manager.

Validate the state parameter

Always validate that the state parameter in the callback matches what you sent. This prevents CSRF attacks.

Handle token expiration

Implement automatic token refresh before making API calls. Check expires_in and refresh proactively.

Request minimal scopes

Only request the permissions your app actually needs. Merchants are more likely to install apps with fewer permissions.

Get Started

Guides

Extensions

Functions

App Bridge

Billing

AI & MCP

Authentication

OAuth 2.0 Authentication

Two install paths

A. Managed install — the merchant clicks Install in our marketplace

B. Re-authorization — your app needs a fresh grant later

Available Scopes

Store Data

Orders & Customers

Inventory & Discounts

Metafields

Content & Files

Shipping & Gift Cards

Billing, Analytics, Settings & Marketing

Email Templates

Authorization Request

Parameters

Token Exchange

Response

Token Refresh

Making Authenticated Requests

Security Best Practices

​OAuth 2.0 Authentication

​Two install paths

​A. Managed install — the merchant clicks Install in our marketplace

​B. Re-authorization — your app needs a fresh grant later

​Available Scopes

​Store Data

​Orders & Customers

​Inventory & Discounts

​Metafields

​Content & Files

​Shipping & Gift Cards

​Billing, Analytics, Settings & Marketing

​Email Templates

​Authorization Request

​Parameters

​Token Exchange

​Response

​Token Refresh

​Making Authenticated Requests

​Security Best Practices

OAuth 2.0 Authentication

Two install paths

A. Managed install — the merchant clicks Install in our marketplace

B. Re-authorization — your app needs a fresh grant later

Available Scopes

Store Data

Orders & Customers

Inventory & Discounts

Metafields

Content & Files

Shipping & Gift Cards

Billing, Analytics, Settings & Marketing

Email Templates

Authorization Request

Parameters

Token Exchange

Response

Token Refresh

Making Authenticated Requests

Security Best Practices