Authentication

Audience: Developer

eshopOS public integrations use:

• Public Integration API (/api/public/v1/*): use API keys or OAuth access tokens.

Private management/admin APIs are not part of the public developer surface.

Public API Credentials

Credential	Prefix	Typical Use	Scope Behavior
System API key (client)	eshopos_test_ck_... / eshopos_live_ck_...	Trusted server-to-server integrations	Can carry broad scopes (for backend only)
Secret key	eshopos_test_sk_... / eshopos_live_sk_...	Server-side app integrations	Read/write when scope allows
Publishable key	eshopos_test_pk_... / eshopos_live_pk_...	Browser/mobile read-safe use	Read-only (public:read)
OAuth access token	eshopos_oat_...	Installed third-party OAuth apps	Scope + app status enforced

Use either:

• Authorization: Bearer <token> (recommended)
• X-API-Key: <token>

Test vs Live Mode

Mode is enforced for public API credentials:

• key prefix encodes mode (test / live)
• request mode can be sent as X-EshopOS-Mode: test|live (or ?mode=test|live)
• mode mismatch returns 403

Public API Example

BASE_URL="http://localhost:8080"
TOKEN="eshopos_test_ck_replace_me"

curl -sS "$BASE_URL/api/public/v1/payments/supported-countries" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-EshopOS-Mode: test"

OAuth App Authentication

OAuth protocol endpoints are under /api/public/v1/oauth/*:

• GET /oauth/authorize
• POST /oauth/authorize/consent
• POST /oauth/token
• POST /oauth/revoke

After code exchange, call public API with returned access_token:

curl -sS "$BASE_URL/api/public/v1/payments/supported-countries" \
  -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN" \
  -H "X-EshopOS-Mode: live"