Авторизація і токени

Публічний API авторизується персональними токенами доступу (PAT). Один токен прив'язаний до акаунту і діє на всі ваші сутності конструктора в межах виданих областей доступу.

Створення токена

Персональний токен створюється в особистому кабінеті, у розділі персональних токенів. Значення токена показується один раз при створенні — збережіть його в надійному місці. На сервері токен зберігається лише в хешованому вигляді, відновити його не можна; якщо загубили — випустіть новий і видаліть старий.

Усі персональні токени починаються з префікса mbp_.

Передача токена

Токен передається в кожному запиті HTTP-заголовком Authorization за схемою Bearer:

Authorization: Bearer mbp_ВАШ_ТОКЕН

Той самий заголовок використовується і для сесійного доступу з веб-кабінету (там це короткоживучий JWT), але для інтеграцій використовуйте саме персональний токен mbp_….

Області доступу (scopes)

У токена є набір областей доступу у форматі ресурс:дія. Читання потребує суфікса :read, зміни — :write. Доступні області:

  • bots:read, bots:write — боти, їхні налаштування, синхронізація, токен бота.
  • reactions:read, reactions:write — реакції, імпорт, тест формул, зв'язки, порядок.
  • labels:read, labels:write — мітки підписників.
  • collections:read, collections:write — колекції та записи.
  • flows:read, flows:write — потоки.
  • integrations:read, integrations:write — інтеграції, підключення, облікові дані.
  • media:write — завантаження в медіабібліотеку.
  • templates:read, templates:write — шаблони ботів.
  • settings:read, settings:write — налаштування.
  • subscribers:read — підписники та історія діалогу (читання).
  • broadcasts:write — розсилки та керування ними.
  • stats:read — статистика і аналітика.
  • billing:read — баланс і тарифи (читання).

Особлива область * надає повний доступ до всього публічного набору ендпоінтів.

Що доступно за токеном, а що ні

За персональним токеном доступні лише конструкторські ендпоінти — ті, що «допомагають будувати бота». Недоступні за PAT (лише з веб-сесії): вхід і реєстрація, мобільні ендпоінти, оплата і поповнення балансу, сповіщення, журнал аудиту, операторське надсилання повідомлень у діалог, вхідні вебхуки і платіжні коллбеки, WebSocket. Запит з mbp_-токеном до такого маршруту поверне 401 або 403.

Якщо токену не вистачає потрібної області для конкретного маршруту — повернеться 403. Детальніше про коди — у гайді про помилки.

Що далі