Authentication
The Stokzone Web Service API authenticates each request with an API key (X-API-Key) sent on every call. Keys can only access endpoints covered by the scopes assigned to them.
X-API-Key header
Add your API key to every request as the X-API-Key header. The key is never sent in the body or query string.
HTTP
X-API-Key: sk_live_xxxxxxxxxxxxScope catalog
Grant each key only the scopes it needs (least-privilege principle). An endpoint returns 403 when the required scope is missing.
| Scope | Description |
|---|---|
products:read | List and read products and variants |
products:write | Create and update product cards |
orders:read | List and read orders |
orders:write | Update order statuses |
inventory:write | Update stock quantities |
prices:write | Update sale prices |
returns:read | Read return and claim records |
returns:write | Approve/update returns and claims |
invoices:read | Read invoice records |
questions:read | Read customer questions |
questions:write | Answer customer questions |
customers:read | Read customer cards |
categories:read | Read the category tree |
brands:read | Read the brand list |
buybox:read | Read buybox status |
shipping:read | Read shipping and shipment info |
shipping:write | Create and update shipments |
reports:read | Read sales and performance reports |
webhooks:manage | Manage outbound webhook subscriptions |
IP allowlisting
You can define an optional IP allowlist per API key. When a list is set, only requests from those IP addresses are accepted; others receive 403.
Authorization errors
401 Unauthorized — API key is missing, invalid or revoked.
401
{
"detail": "Geçersiz veya eksik API anahtarı"
}403 Forbidden — Key is valid but lacks the scope required for this endpoint.
403
{
"detail": "Bu işlem için 'orders:read' yetkisi gerekli"
}