Подключение аккаунтов
Коннектор возвращает реальные данные только после того, как организация-владелец подключит к нему аккаунт. Каждый коннектор объявляет, как он авторизуется; агент подбирает и расшифровывает нужные учётные данные на каждый вызов.
Потоки авторизации
Каждый сервис объявляет один поток авторизации. Каталог использует первые три, mcp_oauth есть только у MCP-сервера, который добавил пользователь:
| Поток авторизации | Описание |
|---|---|
credentials | Ключ API, токен или логин и пароль, которые вставляют в форму подключения. Так подключается большая часть каталога. |
device_code | Пользователь подтверждает подключение на сайте провайдера коротким кодом, а платформа забирает токен (сервисы Яндекса). |
popup_oauth | OAuth во всплывающем окне: пользователь разрешает доступ, токен сохраняется и обновляется автоматически (Google, GitHub, HeadHunter, Ozon, Т-Банк, приложение Битрикс24). |
mcp_oauth | Только для MCP-сервера, который добавил пользователь: OAuth этого сервера с динамической регистрацией клиента и PKCE во всплывающем окне. |
Транспорт (то, как секрет прикрепляется к каждому запросу) это отдельная ось (bearer-заголовок, basic, query-токен, HMAC конкретного вендора и так далее) и обрабатывается самим коннектором.
Где подключаются аккаунты
Аккаунты подключаются в приложении, в Настройки → Коннекторы: форма спрашивает ровно те поля, которые объявляет коннектор, сервис с popup OAuth открывает окно провайдера, сервис с device-code показывает код для подтверждения. Когда вызову нужен ещё не подключённый аккаунт, агент показывает карточку подключения прямо в чате (инструмент request_form). Второй кабинет того же сервиса добавляется там же под своим именем.
Подключением управляют на карточке коннектора в приложении: кто может им пользоваться (видимость), сохранённые поля, адрес вебхука и отключение. В API для интеграций подключение и управление аккаунтами не входят: ключ организации открывает /v1 и MCP-сервер, которые пользуются подключёнными аккаунтами, но не подключают их.
Хранение учётных данных
Подключённые учётные данные шифруются при хранении. Аккаунт принадлежит подключившему; видимость private оставляет его владельцу, org открывает всей организации. При вызове коннектора платформа сама подставляет секрет адресуемого аккаунта в запрос. Секреты коннекторов (ключи API, токены, пароли) в окружение песочницы не попадают: код обращается к коннектору через хост, у которого и лежат креды. В os.environ есть только несекретные реквизиты подключения, собственные переменные пользователя и переменные, которые называет Environment. Увидеть сохранённое значение на карточке коннектора может только тот, кто управляет подключением, и каждый просмотр пишется в аудит.
Несколько аккаунтов (кабинеты)
Один сервис может держать несколько подключённых аккаунтов: несколько кабинетов Ozon, два продавца WB. Каждый из них адресуется суффиксом к сервису (ozon:2, ozon:Top Zip). См. Вызов коннектора.
Выдача коннекторов и учётных данных агенту
Агент вызывает только разрешённые ему коннекторы и может пользоваться подключёнными аккаунтами того, для кого работает, кроме отключённых для него. Выдача устроена в два слоя, оба на карточке интеграций агента в приложении:
Разрешите коннекторы
Список коннекторов решает, какие инструменты у агента есть (wildberries, ozon, …). Коннектор, который агенту не разрешён, просто отсутствует в его наборе инструментов.
Выберите аккаунты
Переключатель у каждого подключённого аккаунта решает, какими аккаунтами агент может пользоваться: разрешённый коннектор, у которого все аккаунты отключены, данных не вернёт.
Агент работает в рамках выдач
В момент исполнения агент дотягивается только до разрешённых коннекторов и неотключённых аккаунтов; всё остальное вне области. То же действует, когда агента зовут через /v1 по его хэндлу.
Как обращаться к агентам из кода, описано в разделе Агенты.
Частые вопросы
Какие потоки авторизации используют коннекторы?
Каждый сервис объявляет один из четырёх потоков авторизации: credentials (ключ API, токен или пароль в форме), popup_oauth (OAuth во всплывающем окне), device_code (подтверждение на сайте провайдера коротким кодом) и mcp_oauth, который есть только у MCP-сервера, добавленного пользователем. Транспорт, прикрепляющий секрет к каждому запросу, это отдельная ось, которой занимается сам коннектор.
Как хранятся учётные данные?
Подключённые учётные данные шифруются при хранении. При вызове коннектора платформа сама подставляет секрет адресуемого аккаунта в запрос. Секреты коннекторов (ключи API, токены, пароли) в окружение песочницы не попадают: код обращается к коннектору через хост, у которого и лежат креды. В os.environ есть только несекретные реквизиты подключения, собственные переменные пользователя и переменные, которые называет Environment.
Может ли один сервис держать несколько аккаунтов?
Да. Один сервис может держать несколько подключённых аккаунтов: несколько кабинетов Ozon, два продавца WB. Каждый из них адресуется суффиксом к сервису: ozon:2 или ozon:Top Zip.
Как агент получает доступ к коннектору и его учётным данным?
В два слоя, оба задаются на карточке интеграций агента в приложении. Список коннекторов решает, какие у агента инструменты; переключатель у каждого аккаунта решает, какими подключёнными аккаунтами он может пользоваться. Агент дотягивается до аккаунтов того, для кого работает, кроме отключённых. Подключения владельца агента до коллег не доходят: коллега запускает общего агента на своих подключениях, в пределах принятых им коннекторов.