Authentication - Shoppex

If you run an internal automation script, use an API key. Use OAuth2 when an app or service should connect to your store through an Allow Access page and get its own tokens, so nobody pastes a key. An OAuth app connects only to the store that created it. To connect Claude or another AI agent, see Agents & CLI.

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 an app that a person on your team connects through an Allow Access page

Your own warehouse worker uses an API key. An ERP or CRM with a “Connect Shoppex” button uses OAuth2: a team member approves the access, and the app gets tokens that act with that person’s access.

Quick decision

Use this shortcut:

I run the tool myself -> API key
People connect an app to the store with an Allow Access page -> OAuth2

An internal deployment helper? API key. An ERP that your team connects with a “Connect Shoppex” button? OAuth2. An app that serves many stores needs one OAuth app in each store: each store creates it and gives the app its client ID and secret.

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. 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`
Shipping physical orders	`orders.read`, `orders.write`
Chargeback tooling	`disputes.read`
Revenue reporting	`analytics.read`
Theme development	`themes.read`, `themes.write`
Catalog sync	`products.read`
CRM sync	`customers.read`
Webhook management	`webhooks.read`, `webhooks.write`

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 -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 an app should connect to your store without anyone pasting a raw API key.

Creating an OAuth app

The store owner, or a team member with the Webhooks or General Settings permission, can manage OAuth apps.

Open the OAuth Apps tab

In dashboard.shoppex.io, go to Settings › Developer › OAuth Apps.

Create the app

Click Create App and fill in:

Name: people see it on the Allow Access page.
Redirect URIs: one per line, up to 20. Each must be a full https:// URL. http:// works only for localhost, 127.0.0.1 and [::1].
Access: the scopes the app can ask for. It can never ask for more.

Click Create App.

Copy the client ID and secret

The next screen shows the client ID (shoc_...) and the client secret (shcs_...). Copy the secret now: Shoppex stores only a hash of it and never shows it again. Keep it on your server, never in a browser or mobile app.

For example: App name ERP Connector, redirect URI https://erp.example.com/oauth/callback, scopes orders.read customers.read.The OAuth Apps tab lists each app with its client ID, redirect URIs, access and last use. From each row you can:

Edit: change the name, redirect URIs and access. The client ID and secret stay the same. Removed scopes stop working right away, also for tokens the app already has. Added scopes apply after someone approves the app again.
Rotate Secret: makes a new secret and shows it once. The old secret stops working right away, so the token endpoint refuses it. Access tokens the app already has keep working until they expire, but the app needs the new secret to refresh them.
Revoke App: ends the app. Its access and refresh tokens stop working right away, and it can’t connect again. You can’t undo this.

Claude and the Shoppex CLI connect without an app here. They show under Settings › Developer › API Keys › Connected Apps.

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

redirect_uri must match one of the app’s redirect URIs exactly. One exception: for an http:// redirect URI on localhost, 127.0.0.1 or [::1], any port matches (host, path and query must still match). An https:// redirect URI on those hosts must match exactly, port included. scope is optional: leave it out to ask for all of the app’s scopes, or send a subset. If you ask for a scope the app does not have, the browser goes back to your redirect URI with error=invalid_scope and your state.Shoppex checks the client and the redirect URI, then sends the merchant to the consent page in the dashboard (dashboard.shoppex.io/oauth/authorize). The merchant signs in if needed, picks the store, sees the requested access and clicks Allow Access. Approving needs the permission to manage API keys.Shoppex then issues a short-lived code (10 minutes, single use) and redirects back to your app:

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

If the merchant clicks Cancel, the redirect carries error=access_denied and your state.Important:

the approval step is interactive, so a third-party site cannot silently mint OAuth codes for a logged-in merchant
an unknown or revoked client_id, or a redirect_uri that is not registered, is shown as an error and never redirected to
the consent page connects the app only to the store that created it; approving it in another store is refused
PKCE (code_challenge with code_challenge_method=S256) is supported for every app; plain is refused
a grant ends when the merchant disconnects the app under Settings → Developer → API Keys → Connected Apps, or when the approving user leaves the store

Token endpoint

Exchange that code for an access token. Send the client ID and secret with HTTP Basic auth, as below, or as client_id and client_secret in the body. The body can be form-encoded or JSON.

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"

If you sent a code_challenge, add code_verifier=... to this request. A code that is expired or already used answers 400 with invalid_grant. A wrong or rotated client secret answers 401 with invalid_client.Example response:

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

Access tokens last one hour. Refresh tokens last 30 days, and each refresh returns a new refresh token: store it and drop the old one. Sending a used refresh token again answers 400 with invalid_grant and ends the whole grant, including its current access token; send the merchant through the authorize step again.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
the token acts with the access of the person who approved it, never more: if that person can’t see products in the dashboard, the token can’t read them either
the app’s scopes limit every token it already has: when the store removes a scope from the app, the app’s tokens lose it on their next request, and the next refresh returns the smaller scope. Adding a scope to the app gives existing tokens nothing; the merchant approves it when the app goes through the authorize step again
if the app no longer allows any scope a token was granted, requests with that token answer 403 and the refresh answers 400 with invalid_grant; send the merchant through the authorize step again

Scopes

Scopes follow a resource.action format, for example products.read, orders.write, or themes.read. Use * for full access. * covers every scope except customers.portal_sessions, which a key must hold by name. 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 (no endpoint uses it since the analytics reports were removed on 2026-10-03)
affiliates.read
affiliates.write
customers.portal_sessions signs a customer into your store’s account page with a one-time link (Portal Sessions). Full Access does not include it, and only the store owner can give it to a key.

Platform & security scopes

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

A scope covers every endpoint of its resource. products.read and products.write also cover shipping zones (/dev/v1/shipping-zones), and orders.write covers shipping and delivering physical orders. 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, apiKey.credentialType is oauth_access_token, apiKey.oauthClientId is the client_id of the app that issued the current access token (shoc_... for an app the store created) and apiKey.oauthClientName is its name.

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.

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.

​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

​Commerce scopes

​Customer & analytics scopes

​Platform & security scopes

​Inspecting the active key

​Key format

​Error responses

​Missing or invalid key

​Shop suspended

​Missing scope

​Regenerating keys

​Best practices

​Use least privilege scopes

​Handle rate-limit headers

​Forward a request id

​Use environment variables

​Keep keys server-side

​Use HTTPS only

​Monitor usage

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

Commerce scopes

Customer & analytics scopes

Platform & security scopes

Inspecting the active key

Key format

Error responses

Missing or invalid key

Shop suspended

Missing scope

Regenerating keys

Best practices

Use least privilege scopes

Handle rate-limit headers

Forward a request id

Use environment variables

Keep keys server-side

Use HTTPS only

Monitor usage