Authentication

How to authenticate with the Shoppex Developer API

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 uses an API key. A third-party ERP or CRM uses 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

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

Creating an API key

1. Open Dashboard

   Go to dashboard.shoppex.io and log in.

2. Navigate to Settings

   Go to Settings in the sidebar.

3. Generate Key

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

4. Choose access

   Pick the smallest scope set your integration needs. Start from a preset, or choose Custom to select scopes one resource at a time. To change the scopes of a key later, use Edit Scopes in its menu.

   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
   Webhook management	webhooks.read, webhooks.write

5. Copy Key

   Copy your API key immediately. It starts with shx_ and will not 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

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

OAuth2

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

1. Log in to dashboard.shoppex.io
2. Go to your Dev API settings
3. Create an OAuth app with:
   • a name
   • one or more redirect URIs
   • the scopes the app can request
4. 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, for example products.read, orders.write, or themes.read. Use * for full access.

The most common mistake here is giving a key more scopes than it needs. A catalog sync must not also get customers.write. A reporting tool only needs read scopes. Grant the minimum and expand later if needed.

Available scopes fall into three groups:

Commerce scopes

• orders.read
• disputes.read
• subscriptions.write
• payment_links.write
• products.read

Customer & analytics scopes

• customers.write
• analytics.read
• analytics.write
• affiliates.read
• affiliates.write

Platform & security scopes

• webhooks.write
• themes.read
• themes.write
• licenses.read
• licenses.write
• security.read
• security.write
• store.read
• store.write
• * for full access

OAuth2 access tokens use these same Dev API scopes. For instance, your app requests orders.read customers.read, the merchant approves, and the exchanged shpat_... token can then only read orders and customers.

Inspecting the active key

Use GET /me/capabilities to inspect the active key at runtime:

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

This response tells you:

• which scopes are active
• whether the key has full access
• which resource groups are readable or writable
• which payment methods are enabled for the shop
• which gated Dev API features are enabled for the shop

Notably, enabledPaymentMethods tells you whether gateways like Stripe, PayPal, or your connected crypto provider (OxaPay, Cryptomus, NowPayments) are active. features.nativeCryptoCheckout tells you which non-custodial native crypto gateways are available.

If you authenticated with OAuth2, the capabilities response also tells you which OAuth client issued the current access token.

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:

1. Go to Settings in your dashboard
2. Revoke the affected key
3. Create a new key with the smallest required scopes
4. 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.

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.