Docs / Authentication

Authentication

Every request needs either an API key (key id + secret) or an OAuth 2.1 access token.

Methods#

Method	Header	Use it for
API key headers recommended	`X-Api-Key: ek_…` `X-Api-Secret: sk_…`	Your own integration with one shop
HTTP Basic	`Authorization: Basic base64(ek_…:sk_…)`	Tools that only support Basic auth
Bearer key pair	`Authorization: Bearer ek_…:sk_…`	Clients that only allow a bearer header
OAuth access token	`Authorization: Bearer at_…`	Apps connected by merchants

X-Api-Key/X-Api-Secret are used if both are present; otherwise the Authorization header is parsed.

Examples

# API key
curl "https://api.ecomone.shop/api/public/v1/products" -H "X-Api-Key: ek_..." -H "X-Api-Secret: sk_..."

# HTTP Basic
curl -u "ek_...:sk_..." "https://api.ecomone.shop/api/public/v1/products"

# OAuth access token
curl "https://api.ecomone.shop/api/public/v1/products" -H "Authorization: Bearer at_..."

API keys#

Key ids look like ek_ + 16 hex characters, secrets like sk_ + 48 hex characters.
A key belongs to exactly one shop and carries the scopes chosen when it was created. The shop owner can change scopes later.
Keys can be deactivated or revoked at any time; both return 401.
Only the shop owner can create, change and revoke keys. The secret is shown once and stored as a SHA-256 hash.

Multiple shops#

An API key always covers one shop. An OAuth connection can cover several shops of the same merchant. In that case add shop_id to every REST request; without it you get 400 shop_required.

cURL

curl "https://api.ecomone.shop/api/public/v1/orders?shop_id=4f6c2a1e-1b2c-4d5e-8f90-123456789abc" \
  -H "Authorization: Bearer at_..."

For OAuth tokens, the merchant can narrow permissions per shop in the backend. The effective scopes are the granted scopes minus anything the merchant switched off for that shop.

When authentication fails#

Missing, wrong, revoked or expired credentials return 401 unauthorized. The response includes WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource", so OAuth-capable clients can discover how to sign in. A missing scope returns 403 forbidden with the scope name in the message. See Errors.