Приложения, токены и scopes

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

Загружаем поисковый индекс…

Приложения, токены и scopes

Приложения

Приложение — доступ одной системы к одному магазину: его scopes, точки, с которыми оно работает, и, если заданы, адреса, с которых оно может обращаться. Приложения создаются в «Настройки → API и вебхуки» тем, у кого есть право управлять API, — по умолчанию владельцем, — и никто не может дать приложению больше, чем есть у него самого.

Приложение действует в магазине как отдельный участник. Заказы, которые оно создаёт, и остатки, которые меняет, подписаны его именем, и магазин видит в истории, что сделала интеграция.

API входит в тариф. Если магазин перейдёт на тариф без него, запросы получают 403 integration_api_not_in_plan, пока магазин не вернётся; приложения и токены остаются как были.

Scopes

Scope открывает ресурс на чтение или на запись: catalog:read, orders:write. Scope записи включает scope чтения своего ресурса. Таблица scopes показывает, какие методы открывает каждый.

Два scope добавляют поля в ответы другого ресурса: costs:read — себестоимость в варианты каталога и позиции заказов, customers:read — контакты, адрес и комментарий покупателя в заказы и получателя в фискальные документы. Без scope этих полей в ответе нет вовсе, а не пусто.

Запрос без scope своего метода получает 403 insufficient_scope. Ответ называет недостающий scope, и магазин добавляет его приложению:

Запрос
curl "https://api.saleya.app/v1/orders" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ответ
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:read"

{
  "type": "insufficient_scope",
  "title": "Scope is missing",
  "status": 403,
  "detail": "This request needs the orders:read scope. The store owner grants it in the app access settings.",
  "required_scope": "orders:read",
  "accepted_scopes": [
    "orders:read"
  ]
}

Токены

  • Токен начинается с saleya_at_. Его последние шесть символов — контрольная сумма: токен с опечаткой отклоняется до поиска, а сканеры секретов узнают утёкший.
  • Магазин хранит только хеш токена и его первые символы, поэтому токен показывается один раз — при выпуске.
  • Срок действия — по желанию. Владелец магазина получает письмо до того, как токен истечёт.
  • У приложения не больше 2 текущих токенов: один в работе и один на замену.

Чтобы сменить токен, выпустите новый на замену старому и выберите, сколько старый ещё проработает. Разверните новый в этот срок. Отзыв действует со следующего запроса; удаление приложения отзывает все его токены.

type у 401Что значит
api_token_missingНет заголовка Authorization: Bearer.
api_token_invalidНеверный формат или контрольная сумма, или такого токена нет.
api_token_expiredСрок действия истёк.
api_token_revokedТокен отозван, приложение удалено или магазин закрыт.

Безопасность токенов

  • Храните токен на своём сервере. Токен в браузере, мобильном приложении или репозитории — утёкший токен.
  • Ограничьте приложение адресами своих серверов: запрос с любого другого адреса получит 403 ip_not_allowed.
  • Владелец магазина получает письмо, когда токен выпущен или отозван и когда меняется доступ приложения.
  • Журнал запросов приложения в панели хранит каждый запрос 30 дней: метод, путь, статус и type отказа, без тел.
  • Если токен утёк, отзовите его сразу: отзыв не ждёт замены.
Следующий гайдМагазин для разработки