Авторизация и API-ключи

Два способа входа

Кто	Чем	Заголовок
Интеграция (1С, SAP, ваш сервер)	API-ключ компании	X-Api-Key: orda_sk_… или Authorization: Bearer orda_sk_…
Человек (веб-кабинет, приложения)	токен пользователя после входа и 2FA	Authorization: Bearer <токен>

Для интеграций используйте только API-ключ: он не зависит от паролей сотрудников, не требует 2FA и имеет ровно те права, которые нужны обмену.

Как получить ключ

Администратор компании (с правом «Интеграции → управление») создаёт ключ в кабинете или запросом:

curl -s -X POST "$ORDA_API/api-keys" -H "Authorization: Bearer <токен администратора>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "1С: выгрузка заказов", "scopes": ["orders.view", "orders.create", "orders.edit", "customers.view", "customers.create", "customers.edit"] }'

В ответе поле key — полный ключ, показывается один раз. В Orda хранится только его хэш, восстановить ключ нельзя — только выпустить новый. Ключ можно ограничить сроком (expiresAt) и отозвать в любой момент (DELETE /api-keys/{id}) — он перестаёт работать сразу.

Права ключа (scopes)

Право имеет вид раздел.действие. Доступные ключам разделы:

Раздел	Что внутри
orders	заказы: view, create, edit, delete
customers	точки доставки (клиенты)
warehouses, vehicles, drivers	склады, машины, водители
planning	построение плана маршрутов: view, create
routes	утверждение плана: approve
integrations	вебхуки: view, create, edit, delete

Полный список: GET /api-keys/scopes. Пользователи, роли, настройки компании, оплата и выпуск ключей ключам недоступны никогда. Нужное право для каждого метода указано в справочнике (поле x-orda-permission).

Ключ действует от имени сотрудника, который его создал, и никогда не сильнее его текущих прав: если у сотрудника забрали право или его заблокировали — ключи, которые он выпустил, сразу теряют это право или перестают работать. Поэтому ключи для постоянной интеграции лучше выпускать от служебной учётной записи администратора.

Правила хранения

• Храните ключ в хранилище секретов (в 1С — в защищённых настройках/безопасном хранилище, не в коде и не в справочнике, который видят все пользователи).
• Один ключ — одна интеграция. Для теста и боевого контура — разные ключи (и разные компании, см. Песочница).
• Ключ попал в чат, письмо или репозиторий — отзовите его и выпустите новый.
• Вызывайте API только с сервера. Ключ в браузере или мобильном приложении — утечка.

Ответы при ошибках доступа

Код	code	Что значит
401	INVALID_API_KEY	ключ неверный, отозван, истёк или его владелец заблокирован
403	FORBIDDEN	у ключа нет нужного права (message называет право)
403	API_KEY_NOT_ALLOWED	метод недоступен по ключу (например, управление пользователями)
429	RATE_LIMITED	превышен лимит запросов, см. Ошибки и лимиты