Authentication
Organization API keys in the Authorization header — test and live, scopes, IP allowlist and rotation.
Every request carries an organization API key:
GET /v1/orders HTTP/1.1
Host: partner.sapamoto.kz
Authorization: Bearer sk_live_2Hq8…There are no sessions, cookies or user tokens on the Partner API — user tokens of the cabinet or the back-office are
refused with 401. Only TLS 1.2+ is accepted.
Test and live keys
| Prefix | Environment | Host | When |
|---|---|---|---|
sk_test_ | sandbox | https://partner-sandbox.sapamoto.kz | right after your organization is created, before the contract |
sk_live_ | production | https://partner.sapamoto.kz | after the integration checklist; your account manager enables live mode |
The environment of the key decides everything: orders, webhook endpoints and the request journal of test and live
keys never mix. Live orders of an organization that is not active yet (no signed contract) are refused with
403 organization_not_active; the test key keeps working.
Creating a key
In the cabinet, section «Интеграция», create a key. Choose the environment, a name (e.g. erp-prod), the scopes and
optionally an IP allowlist. The secret is shown once and stored on our side as a hash — if you lose it, create a
new key and revoke the old one.
Keep keys on your servers. Never put a key into a mobile app, a browser page or a public repository. A leaked key can create orders on your account.
Scopes
| Scope | Allows |
|---|---|
orders.read | GET /v1/orders, /orders/{id}, /track, /proof, /slots |
orders.write | POST /v1/quotes, /orders, /orders/batch, PATCH /orders/{id}, /ready, /cancel, /payment |
points.read | GET /v1/pickup-points |
finance.read | GET /v1/balance |
webhooks.manage | GET/POST /v1/webhooks, PUT /v1/webhooks/{id} |
A new key gets all scopes by default. A request outside the key's scopes gets 403 forbidden. Give a read-only
dashboard only orders.read.
IP allowlist
A key may carry a list of addresses or CIDR ranges (203.0.113.10, 198.51.100.0/24). Requests from other
addresses are refused with 403 api_key_ip_not_allowed.
Rotation and revocation
Each environment allows two active keys, so you can rotate without downtime:
- create the second key;
- deploy it to all your servers;
- revoke the old key in the cabinet.
A revoked key stops working within 60 seconds everywhere and returns 401 unauthorized. Revocations are written
to the audit log.
Errors
| Status | Code | Why |
|---|---|---|
| 401 | unauthorized | no Authorization: Bearer, an unknown or revoked key |
| 403 | forbidden | the key lacks the scope |
| 403 | api_key_ip_not_allowed | the request came from outside the key's allowlist |
| 403 | feature_disabled | the Partner API is not enabled for your organization yet |
| 403 | organization_not_active | live order of an organization without an active contract |