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 или через приложение-аутентификатор).
- Отправьте пользователя на эндпоинт авторизации с
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. - При необходимости пользователь входит в MonoChat. Страница одобрения называет ваше приложение и показывает Запускать пользовательские методы от вашего имени. Пользователь может выбрать Организации, к которым приложение получит доступ (все его, если ничего не выбрано), вводит 6-значный код подтверждения и нажимает Разрешить.
- MonoChat возвращает пользователя на ваш
redirect_uriсcode,stateиiss. Е сли пользователь нажмёт Отклонить, вместо этого придётerror=access_denied. - Обменяйте код на эндпоинте токена в течение 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>
Повторное подключение того же пользователя к вашему приложению заменяет его прежнее разрешение.