Перейти к основному содержимому

OAuth для партнёрских приложений

Партнёрское приложение, инструмент автоматизации или собственное приложение, работающее от имени пользователя MonoChat, может вызывать API пользовательских функций (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) с токеном доступа OAuth вместо API-токена. Пользователь одобряет приложение на странице MonoChat, выбирает организации, к которым оно получит доступ, и в любой момент может отозвать его в разделе Подключённые приложения в настройках профиля.

API-токены продолжают работать на том же эндпоинте. OAuth подходит приложению, которое действует от имени других людей: оно никогда не видит пароль или API-токен, а каждый пользователь может отключить его сам.

Приложение действует как пользователь

Вызов с токеном доступа выполняется от имени пользователя, одобрившего приложение, с его ролями. Он запускает только пользовательские методы организации и только в организациях, где пользователь является агентом.

Получение клиента​

Запросите у MonoChat клиента для своего приложения. MonoChat регистрирует его с такими данными:

  • название приложения, которое показывают страница одобрения и Подключённые приложения;
  • URI перенаправления с точным совпадением: адреса https или http на localhost, 127.0.0.1 либо [::1] (любой порт);
  • области, которые оно может запрашивать: custom-functions:run для этого API.

Вы получаете ID клиента (начинается с monochat_rc_) и секрет клиента (начинается с monochat_cs_). Секрет показывается один раз; MonoChat хранит только его хеш. Храните его на своём сервере, никогда в браузере или мобильном приложении.

Приложение, которое не может хранить секрет, например работающее в браузере или на компьютере пользователя, может вместо этого использовать в качестве ID клиента URL документа метаданных клиента, как это делают MCP-клиенты. Тогда оно не отправляет секрет.

Эндпоинты​

Метаданные сервера авторизации по адресу https://app.monochat.ai/.well-known/oauth-authorization-server перечисляют все эндпоинты. В white-label или самостоятельно размещённой установке используйте собственный адрес этой установки.

ПараметрЗначение
Эндпоинт авторизацииhttps://app.monochat.ai/oauth/authorize
Эндпоинт токенаhttps://app.monochat.ai/oauth/token
Эндпоинт отзываhttps://app.monochat.ai/oauth/revoke
Ресурсhttps://app.monochat.ai/api/custom-functions
Областьcustom-functions:run
Аутентификация клиентаHTTP Basic или client_id и client_secret в теле запроса

Метаданные самого ресурса находятся по адресу https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Подключение пользователя​

MonoChat использует поток с кодом авторизации и PKCE (S256). У пользователя должна быть настроена двухэтапная проверка (по e-mail или через приложение-аутентификатор).

  1. Отправьте пользователя на эндпоинт авторизации с response_type=code, вашим client_id, зарегистрированным redirect_uri, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, параметром state и code_challenge с code_challenge_method=S256.
  2. При необходимости пользователь входит в MonoChat. Страница одобрения называет ваше приложение и показывает Запускать пользовательские методы от вашего имени. Пользователь может выбрать Организации, к которым приложение получит доступ (все его, если ничего не выбрано), вводит 6-значный код подтверждения и нажимает Разрешить.
  3. MonoChat возвращает пользователя на ваш redirect_uri с code, state и iss. Если пользователь нажмёт Отклонить, вместо этого придёт error=access_denied.
  4. Обменяйте код на эндпоинте токена в течение 5 минут:
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

Ответ содержит access_token (начинается с monochat_at_), действующий expires_in секунд (один час), refresh_token (начинается с monochat_rt_) и выданный scope.

Вызов API​

Передайте токен доступа как bearer-токен:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
СтатусКогда
401Токен неизвестен, истёк или отозван либо выдан для другого ресурса, например MCP-сервера. Заголовок WWW-Authenticate указывает на метаданные ресурса.
403Организация не входит в те, что пользователь разрешил приложению, у пользователя нет доступа к организации, или разрешение не включает custom-functions:run.
429Достигнут лимит; подождите столько секунд, сколько указано в Retry-After. Вызовы считаются за минуту: 120 на разрешение и 1200 на клиента, помимо собственного лимита организации для этого эндпоинта.

Обновление и отзыв​

  • Обновление: до истечения токена доступа вызовите эндпоинт токена с grant_type=refresh_token и refresh_token. Каждое обновление возвращает новый токен обновления; используйте новый. Токен обновления, повторно использованный более чем через минуту после замены, завершает разрешение.
  • Срок действия: разрешение заканчивается через 90 дней после последнего обновления, когда пользователь отзывает его в разделе Подключённые приложения или когда пользователь меняет или сбрасывает пароль. После этого пользователь должен снова одобрить приложение.
  • Отзыв: чтобы отключить пользователя, отправьте токен доступа или обновления на эндпоинт отзыва с аутентификацией вашего клиента:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Повторное подключение того же пользователя к вашему приложению заменяет его прежнее разрешение.