Authentication

If you are using Claude Code, Codex, or an internal automation script for themes, use an API key with scopes themes.read themes.write. Use OAuth2 only if you are building an external app that other merchants install.

Authentication Modes

Shoppex supports two Bearer token modes for the Dev API:

API keys for server-to-server integrations you manage directly
OAuth2 access tokens for installable apps and third-party connectors

Your own warehouse worker would use an API key. A third-party ERP or CRM would use OAuth2, so the merchant clicks “Connect Shoppex” instead of pasting a raw key.

Quick Decision

Use this shortcut:

I run the tool myself -> API key
I am building an installable third-party app -> OAuth2

Claude Code editing your own theme? API key. Codex running your internal deployment helper? API key. ERP integration for many merchants? OAuth2.

API Keys
OAuth2

Shoppex uses API keys for authentication. Each key belongs to exactly one shop and can be limited with scopes.

Creating an API Key

Open Dashboard

Go to dashboard.shoppex.io and log in.

Navigate to Settings

Go to Settings in the sidebar.

Generate Key

In the Developer API section, click Generate New API Key.

Choose Access

Pick the smallest scope set your integration needs.Common scope combinations:

Integration	Scopes
Fulfillment / ERP sync	`orders.read`
Chargeback tooling	`disputes.read`
Report automation	`analytics.read`, `analytics.write`
Theme development	`themes.read`, `themes.write`
Catalog sync	`products.read`
CRM sync	`customers.read`
Reseller program admin	`reseller_programs.read`, `resellers.read`, `resellers.write`
Reseller portal automation	`reseller_sales.read`, `reseller_payouts.read`, `reseller_payouts.write`, `reseller_stock.read`, `reseller_stock.write`
Webhook management	`webhooks.read`, `webhooks.write`

Copy Key

Copy your API key immediately. It starts with shx_ and won’t be shown again.

Store your API key securely. If compromised, regenerate it immediately.

Using Your API Key

Include the API key in the Authorization header with the Bearer scheme:

curl -X GET https://api.shoppex.io/dev/v1/invoices \
  -H "Authorization: Bearer shx_your_api_key_here"

const response = await fetch('https://api.shoppex.io/dev/v1/invoices', {
  headers: {
    'Authorization': 'Bearer shx_your_api_key_here'
  }
});

import requests

response = requests.get(
    'https://api.shoppex.io/dev/v1/invoices',
    headers={'Authorization': 'Bearer shx_your_api_key_here'}
)

$ch = curl_init('https://api.shoppex.io/dev/v1/invoices');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer shx_your_api_key_here'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

OAuth2 is the better fit when you want an external app to connect to a shop without asking the merchant for a raw API key.

Creating an OAuth App

Log in to dashboard.shoppex.io
Go to your Dev API settings
Create an OAuth app with:
- a name
- one or more redirect URIs
- the scopes the app may request
Copy the client_id and client_secret

For example: App name ERP Connector, redirect URI https://erp.example.com/oauth/callback, scopes orders.read customers.read.

Authorize Endpoint

The merchant browser is redirected to:

GET /dev/v1/oauth/authorize?response_type=code&client_id=shoc_xxx&redirect_uri=https%3A%2F%2Ferp.example.com%2Foauth%2Fcallback&scope=orders.read%20customers.read&state=sync_42

If the user is logged in and allowed to approve integrations for the active shop, Shoppex first shows a Shoppex-hosted approval screen.After the merchant clicks Approve and continue, Shoppex issues a short-lived code and redirects back to your app.

https://erp.example.com/oauth/callback?code=shoa_abc123&state=sync_42

Important:

the approval step is intentionally interactive, so a third-party site cannot silently mint OAuth codes for a logged-in merchant
the approval submit is protected with a Shoppex CSRF token behind the hosted approval page

Token Endpoint

Exchange that code for an access token:

curl https://api.shoppex.io/dev/v1/oauth/token \
  -X POST \
  -H "Authorization: Basic $(printf 'shoc_xxx:shcs_xxx' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=shoa_abc123&redirect_uri=https%3A%2F%2Ferp.example.com%2Foauth%2Fcallback"

Example response:

{
  "access_token": "shpat_xxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "shprt_xxx",
  "scope": "orders.read customers.read"
}

Refresh flow:

curl https://api.shoppex.io/dev/v1/oauth/token \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "shprt_xxx",
    "client_id": "shoc_xxx",
    "client_secret": "shcs_xxx"
  }'

Using The Access Token

After the exchange, call normal Dev API endpoints with the OAuth access token:

curl https://api.shoppex.io/dev/v1/orders \
  -H "Authorization: Bearer shpat_your_access_token_here"

Important:

OAuth token responses follow the normal OAuth2 JSON format
normal /dev/v1/* resource calls still use the standard Shoppex Dev API response envelope
scopes still apply exactly the same way as for API keys

Scopes

Scopes follow a resource.action format: products.read, orders.write, themes.read, etc. Use * for full access. The most common mistake here is giving a key more scopes than it needs. A catalog sync should not also get customers.write. A reporting tool only needs read scopes. Grant the minimum and expand later if needed. You can inspect the currently active key with:

curl https://api.shoppex.io/dev/v1/me/capabilities \
  -H "Authorization: Bearer shx_your_api_key_here"

Key Format

Prefix	Description
`shx_`	Shoppex API Key (32 characters after prefix)
`shoc_`	OAuth client id
`shcs_`	OAuth client secret
`shoa_`	OAuth authorization code
`shpat_`	OAuth access token
`shprt_`	OAuth refresh token

Example: shx_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Error Responses

Missing or Invalid Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key. Expected: Authorization: Bearer shx_...",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Shop Suspended

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Your shop has been suspended.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Missing Scope

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required API scope.",
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

Regenerating Keys

If an API key is compromised:

Go to Settings in your dashboard
Revoke the affected key
Create a new key with the smallest required scopes
Update your integration with the new key

The old key is immediately invalidated. All requests using it will fail with 401 Unauthorized.

Best Practices

Use least privilege scopes

Give every integration only the scopes it really needs. A reporting tool needs products.read and payments.read — not *.

Handle rate-limit headers

Read X-RateLimit-Remaining and Retry-After. When remaining hits 0, back off until the reset window passes instead of hammering the API.

Forward a request id

If your worker is processing job_123, send X-Request-Id: job_123 so your logs and Shoppex support traces line up perfectly.

Use environment variables

Never hardcode API keys in your source code.

export SHOPPEX_API_KEY=shx_your_api_key_here

const apiKey = process.env.SHOPPEX_API_KEY;

Keep keys server-side

Never expose your API key in client-side code (browsers, mobile apps). Make API calls from your backend server.

Use HTTPS only

Always use HTTPS when making API requests to prevent key interception.

Monitor usage

Check your dashboard regularly for unusual API activity.

Start Here

Concepts

Webhooks

Headless Commerce

Use Cases

Embed SDK

Authentication Modes

Quick Decision

Creating an API Key

Using Your API Key

Creating an OAuth App

Authorize Endpoint

Token Endpoint

Using The Access Token

Scopes

Key Format

Error Responses

Missing or Invalid Key

Shop Suspended

Missing Scope

Regenerating Keys

Best Practices

​Authentication Modes

​Quick Decision

​Creating an API Key

​Using Your API Key

​Creating an OAuth App

​Authorize Endpoint

​Token Endpoint

​Using The Access Token

​Scopes

​Key Format

​Error Responses

​Missing or Invalid Key

​Shop Suspended

​Missing Scope

​Regenerating Keys

​Best Practices

Authentication Modes

Quick Decision

Creating an API Key

Using Your API Key

Creating an OAuth App

Authorize Endpoint

Token Endpoint

Using The Access Token

Scopes

Key Format

Error Responses

Missing or Invalid Key

Shop Suspended

Missing Scope

Regenerating Keys

Best Practices