Authentication and API keys

Who	With	Header
Integration (1C, SAP, your server)	company API key	X-Api-Key: orda_sk_… or Authorization: Bearer orda_sk_…
A person (web app, mobile apps)	user access token after sign-in and 2FA	Authorization: Bearer <token>

Integrations should use API keys only: they do not depend on staff passwords, need no 2FA and carry exactly the rights the exchange needs.

Getting a key

An administrator (permission “Integrations → manage”) creates a key in the web app or with:

curl -s -X POST "$ORDA_API/api-keys" -H "Authorization: Bearer <admin token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "1C order export", "scopes": ["orders.view", "orders.create", "orders.edit", "customers.view", "customers.create", "customers.edit"] }'

The key field is the full key, shown once. Orda stores only its hash. Keys may have an expiry (expiresAt) and can be revoked at any time (DELETE /api-keys/{id}) — effective immediately.

Scopes

A scope is section.action. Sections available to keys: orders, customers, warehouses, vehicles, drivers, planning (view, create), routes (approve), integrations (webhooks: view, create, edit, delete). Full list: GET /api-keys/scopes. Users, roles, company settings, billing and key management are never available to keys. The permission of each endpoint is in the reference (x-orda-permission).

A key acts on behalf of the person who created it and is never stronger than that person’s current rights: if they lose a right or are blocked, their keys lose it or stop working at once. Issue long-lived integration keys from a dedicated service administrator account.

Keeping keys safe

• Store keys in a secret store, never in code or in a catalog every user can read.
• One key per integration; separate keys (and companies) for test and production.
• A key leaked into chat, e-mail or a repository — revoke it and issue a new one.
• Call the API from servers only; a key in a browser or mobile app is a leak.

Access errors

Status	code	Meaning
401	INVALID_API_KEY	wrong, revoked or expired key, or its owner is blocked
403	FORBIDDEN	the key lacks a permission (named in message)
403	API_KEY_NOT_ALLOWED	endpoint not available with keys (e.g. user management)
429	RATE_LIMITED	rate limit, see Errors and limits