Аутентификация и ключи API
Публичные вызовы проверки не требуют учетных данных. Все вызовы под https://app.tanba-ooh.kz/api/v1 требуют ключ API или сессию консоли.
Создание ключа
Администратор организации оператора или уполномоченного органа открывает в консоли раздел «Интеграции» и создает ключ. Секрет выглядит так:
tnbk_<prefix>_<secret>Он показывается один раз. Платформа хранит только его хеш, поэтому потерянный ключ восстановить нельзя: отзовите его и создайте новый.
Передача ключа
curl -H 'Authorization: Bearer tnbk_EXAMPLE_secret' https://app.tanba-ooh.kz/api/v1/structures?limit=10Те же маршруты работают и с cookie сессии консоли. Вызов, который меняет данные, в этом случае должен нести заголовок X-Tanba-CSRF.
Права доступа
| Право | Что разрешает |
|---|---|
read:approvals | Согласования, их манифесты, материалы и конверты, согласования в CSV |
read:structures | Конструкции и их выгрузка в CSV |
read:stats | Операционный отчет и его разделы в CSV |
read:billing | Расчетные периоды, денежный отчет и его разделы в CSV |
read:creatives | Проверка рекламных материалов по хеш-сумме |
read:inventory | Экраны рынка с разрешенными продавцами и фрагментами OpenRTB |
write:submissions | Создать заявку и загрузить ее материал, больше ничего |
write:plays | Передавать показы из вашей CMS; только администраторы операторов. Администраторы рекламных платформ с ним передают заявки на показанные показы и читают их сверку |
relay:commands | Получение и подтверждение подписанных команд установки CMS; только администраторы оператора |
На странице каждой операции указано право, которое ей нужно.
Чего ключ не может никогда
- Ключ может получить только те права, которые есть у создавшего его человека, и при каждом вызове действует с его текущими правами в организации. Если человека понизили или он ушел, ключ сужается или перестает работать.
- Ключ никогда не доходит до управления ключами, управления вебхуками, управления пользователями, модерации и решений по согласованию. Это остается за людьми в консоли.
- Ключи несут права доступа, а не роли. Ничто в API не выдает роль.
Ошибки
| Статус | code | Значение |
|---|---|---|
| 401 | invalid_api_key | Ключ неизвестен, отозван или записан неверно |
| 401 | unauthenticated, session_expired | Нет действующей сессии |
| 403 | key_scope_denied | У ключа нет права, которое нужно этому вызову |
| 403 | key_route_denied | Ни один ключ не может вызвать этот маршрут |
| 429 | rate_limited | Слишком много запросов; дождитесь Retry-After |
Создание ключа, его отзыв и каждый отказ для действующего ключа записываются в журнал аудита вашей организации.