База знаний GetMyBot

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

Персональные токены GetMyBot: как создать, как передавать в заголовке и какие нужны области доступа.

На этой странице

Публичный API авторизуется персональными токенами доступа (PAT). Один токен привязан к одному кабинету и действует на сущности конструктора этого кабинета в пределах выданных областей доступа.

Создание токена

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

Все персональные токены начинаются с префикса mbp_.

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

Токен передаётся в каждом запросе HTTP-заголовком Authorization по схеме Bearer:

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

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

Кабинет токена

Токен работает ровно в одном кабинете. По умолчанию это ваш собственный; если вам выдали доступ к чужому кабинету, при создании токена можно выбрать его: в API это поле account_id в теле POST /api/tokens, в кабинете: выпадающий список над сроком действия. Список доступных кабинетов отдаёт GET /api/account/cabinets.

Что это значит на практике:

  • GET /api/bots под таким токеном возвращает боты выбранного кабинета: ни ваших собственных, ни третьего кабинета в списке не будет.
  • Обращение к боту другого кабинета отвечает 404, как к чужому боту: по токену нельзя проверить, существует ли идентификатор за пределами его кабинета.
  • Права остаются вашими: токен не расширяет доступ, а ограничивает его одним кабинетом. Что именно можно делать с ботом, решают права участника (роль в кабинете плюс поботные гранты).
  • Токен, выпущенный для чужого кабинета, действует с вашими правами в этом кабинете. Счета кабинета (/api/billing/*) читаются только с правом кабинета billing.read, создание проектов: с правом bots.create. Полный доступ токена (область *) прав кабинета не даёт.
  • Если доступ к кабинету отозвали, токен перестаёт работать сразу, со следующего запроса: отзывать его отдельно не нужно.

Кабинет, доступный через бота

GET /api/account/cabinets показывает у каждого кабинета поле source:

  • self: ваш собственный кабинет;
  • account: вам выдан доступ к кабинету, права определяет роль;
  • bot: вы попадаете в кабинет только через расшаренного бота. Прав кабинета у вас там нет.

С кабинетом source: "bot" работают операции с этим ботом в пределах поботных прав, а всё, что относится к кабинету целиком, отклоняется: подключение бота, биллинг и т.п. REST отвечает 403 с {"error":"missing cabinet right"}, а если участник есть, но нужного права нет: missing cabinet right: <право>. В MCP это ошибка инструмента permission denied: missing cabinet right (например, connect_bot требует bots.create, инструменты биллинга: billing.read или billing.write).

Чтобы это исправить, владелец кабинета приглашает вас в карточке «Доступ к кабинету» с нужным правом. Перевыпускать токен не нужно: он начнёт работать со следующего запроса после того, как вы примете приглашение.

Токены, выпущенные до появления этой возможности, привязаны к вашему собственному кабинету. Если такой токен работал с ботом, расшаренным из чужого кабинета, выпустите для этого кабинета отдельный токен.

Области доступа (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. Подробнее про коды: в гайде об ошибках.

Scopes для агентных функций

  • managed_ai:invoke и managed_ai:usage:read: provider-neutral AI-вызовы и usage.
  • copilot:use: lifecycle Copilot proposal. Для diagnostic достаточно journey:read, для изменений графа дополнительно нужен journey:edit.
  • journey:read и journey:edit: Flow Intelligence и Explainable Replay.
  • Управление Meta connections использует существующие integration/bot scopes и дополнительно проверяет права кабинета и конкретного бота.

MCP применяет те же проверки fail-closed и не расширяет кабинет или bot membership токена.

Что дальше