amarix

Доступ

Ключи доступа

Внешние интеграции работают по ключу. Ключ говорит платформе, кто пришёл, в каком бренде он работает и что ему разрешено.

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

Ключ интеграции

Выглядит как csh_at_ и 64 шестнадцатеричных символа — 71 символ целиком. Передаётся заголовком:

заголовок
Authorization: Bearer csh_at_0123456789abcdef...

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

Как получить

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

  • название интеграции — оно попадёт в журнал и поможет потом понять, чей это ключ;
  • список нужных прав либо пометка «полный доступ в пределах магазина»;
  • срок годности, если ключ временный.

Магазин указывать не нужно: ключ автоматически привязывается к тому магазину, в админке которого его выпустили. Работать в другом магазине он не сможет.

Срок жизни и отзыв

У ключа может быть срок годности, а может не быть — тогда он действует бессрочно. Отзыв срабатывает немедленно, кеша нет. Отозванный ключ неотличим от несуществующего: обе ситуации дают 401 Unauthorized.

Ключ производственной площадки

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

запрос к производственному API
curl -s https://api.amarix.ru/production-api/me \
  -H "Authorization: Bearer ваш_ключ_площадки"

Про CSRF-токены

Если вы видели упоминание заголовка X-CSRF-Token — к вам это не относится. Защита от подделки межсайтовых запросов работает только для браузерных сессий с куками. Любой запрос с заголовком Authorization её не касается вовсе.

Проверить, что ключ живой

Самый дешёвый способ — запросить небольшой список и посмотреть на код ответа.

curl -i -s https://api.amarix.ru/orders/admin/all?limit=1 \
  -H "Authorization: Bearer csh_at_ваш_ключ" | head -1

Ошибки доступа

Тексты приведены дословно, как их отдаёт сервер — по ним удобно искать в своих логах.

Ошибки

КодОтвет сервераКогда возникаетЧто делать
401{"error":"Unauthorized"}Заголовка нет; ключ не начинается с csh_at_; ключ отозван, просрочен или неизвестен; учётная запись автора ключа потеряла права суперадминистратора.Проверьте заголовок и статус ключа. Если ключ точно верный — почти всегда дело в учётной записи автора.
401{"error":"Invalid token"}Значение похоже на токен сессии, но подпись не сходится.Убедитесь, что передаёте ключ интеграции, а не токен из браузера.
401{"error":"Missing Authorization: Bearer <apiKey>"}Запрос к производственному API без заголовка авторизации.Добавьте заголовок с ключом площадки.
401{"error":"Invalid or inactive API key"}Ключ площадки неизвестен или площадка выключена.Проверьте ключ. После отзыва старый ключ может работать ещё до 30 секунд.
403{"error":"Forbidden: Missing permission <ключ права>"}У ключа нет права, которое требует эндпоинт.Перевыпустите ключ с нужным правом — добавить право в существующий ключ нельзя.
403{"error":"Forbidden: brand not allowed"}Обращение к записи чужого бренда по идентификатору.Работайте в границах своего бренда. Каждая такая попытка попадает в журнал безопасности.
403{"error":"Forbidden: no brand access configured"}У ключа нет ни одного бренда, а эндпоинт требует брендовой привязки.Перевыпустите ключ так, чтобы он получил бренд.

Дальше — как устроены права и почему запрос видит только свой бренд.