Authentication
Every request carries your key as a bearer token:
Authorization: Bearer bk_live_7f3a9c2b1d4e_4Kd9wQ…
^^ ^^^^ ^^^^^^^^^^^^ ^^^^^^
| | | secret — we store only its SHA-256
| | public id — safe to log, quote it to support
| environment — checked against the host you called
fixed prefix
The secret is shown once, when the key is created. We cannot recover it; a lost key is rotated, not retrieved.
Scopes#
A key carries only the scopes it was granted, and every endpoint declares the one it
needs. A key that syncs stock has no business reading your wallet, and asking for
something outside its grant returns 403 missing_scope naming the scope required.
| Scope | Covers |
|---|---|
catalog.read |
Categories, attributes, languages, countries, currencies, locations |
products.read / products.write |
Your catalog |
orders.read / orders.write |
Orders, labels, invoices, returns |
messages.read / messages.write |
Buyer conversations |
questions.read / questions.write |
Public listing questions |
wallet.read / wallet.withdraw |
Balances and payouts |
company.read / company.write |
Your company profile and settings |
webhooks.manage |
Webhook endpoints and their delivery log |
Rate limits#
60 requests per minute and 5 000 per day by default, per key. A 429 always carries
Retry-After in seconds — respect it rather than retrying immediately.
Bulk product writes have their own endpoint precisely so a catalog import does not spend your ordinary budget: see Sync your catalog.
Keeping a key safe#
- Treat it like a password: server-side only, never in a browser or a mobile app.
- Use a separate key per environment, which the prefix enforces anyway.
- Rotate if it may have leaked. Revocation is immediate.
- Every response returns
X-Request-Id. Quote it to support — it identifies the exact request in our audit trail.