Skip to main content

Developers: Credentials (Secret + Publishable)

What It Is​

The Credentials tab manages a developer-focused key pair:

  • Secret key (sk): server-side, can perform write operations when scoped
  • Publishable key (pk): browser-safe, read-only

Both keys are generated together in one action.

Prefixes​

  • Secret: eshopos_test_sk_... / eshopos_live_sk_...
  • Publishable: eshopos_test_pk_... / eshopos_live_pk_...

When To Use Each Key​

Secret Key​

  • Use in backend services, API servers, webhooks processors, queues
  • Use when you need write-capable calls (POST, PUT, DELETE)

Publishable Key​

  • Use in browser storefront or client-side widgets
  • Use for read-only calls (GET) where exposing token is acceptable

What Will Fail​

If a publishable key attempts write operations, API returns 403 (insufficient_scope).

Where It Is Managed​

  • Dashboard: Settings -> Developers -> Credentials

Merchant API Routes​

  • GET /api/v1/merchant/api-keys
  • POST /api/v1/merchant/api-keys
  • POST /api/v1/merchant/api-keys/{keyID}/rotate
  • POST /api/v1/merchant/api-keys/{keyID}/revoke

Working Examples​

Secret Key Example (server-side)​

BASE_URL="http://localhost:8080"
SECRET_KEY="eshopos_test_sk_replace_me"
STORE_ID="replace_with_store_id"

curl -sS -X POST "$BASE_URL/api/public/v1/stores/$STORE_ID/cart" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "X-EshopOS-Mode: test" \
  -H "Content-Type: application/json"

Publishable Key Example (frontend/read)​

const response = await fetch('http://localhost:8080/api/public/v1/payments/supported-countries', {
  headers: {
    Authorization: `Bearer ${import.meta.env.VITE_ESHOPOS_PUBLISHABLE_KEY}`,
    'X-EshopOS-Mode': 'test',
  },
});

const data = await response.json();
console.log(data);

Key Handling Rules​

  • Do not embed secret keys in frontend bundles
  • Use separate test/live credentials
  • Rotate keys when team members change or keys are exposed