Подключение аккаунтов
Коннектор возвращает реальные данные только после того, как организация-владелец подключит к нему аккаунт. Каждый коннектор объявляет, как он авторизуется; ассистент подбирает и расшифровывает нужные учётные данные на каждый вызов.
Схемы авторизации
Коннекторы используют одну из трёх схем, объявленную для каждого сервиса:
| Field | Type | Description |
|---|---|---|
| credentials | схема | API-ключ, токен или basic-авторизация, вставленные на экране подключения. Преобладающая схема в каталоге. |
| popup_oauth | схема | OAuth-авторизация во всплывающем окне — пользователь подтверждает доступ, токен захватывается автоматически. |
| device_code | схема | Device-code: пользователь подтверждает подключение на сайте провайдера по короткому коду (используется рядом сервисов Яндекса). |
Транспорт — то, как секрет прикрепляется к каждому запросу — это отдельная ось (bearer-заголовок, basic, query-токен, HMAC конкретного вендора и так далее) и обрабатывается самим коннектором.
Где подключаются аккаунты
Аккаунты подключаются в интерфейсе продукта в настройках организации; OAuth-коннекторы также показывают кнопку подключения прямо в чате через инструмент request_form, когда вызову нужен ещё не подключённый аккаунт. Программно метаданные подключения (какие поля нужны коннектору) доступны по GET /api/v1/connectors/metadata.
Хранение учётных данных
Подключённые учётные данные шифруются при хранении (Fernet) и хранятся для каждого пользователя. Ассистент никогда не отдаёт сырой секрет; в момент исполнения он подбирает и расшифровывает учётные данные для адресуемого аккаунта.
Несколько аккаунтов (кабинеты)
Один сервис может держать несколько подключённых аккаунтов — несколько кабинетов Ozon, два продавца WB. Каждый — это адресуемый instance; нацельтесь на один через instance_id или суффикс сервиса (ozon:Top Zip). См. Вызов коннектора.
Выдача коннекторов и учётных данных агенту
Агент ограничен теми коннекторами и учётными данными, которые вы ему явно выдали. Выдача — это два слоя: какие у него инструменты и какие аккаунты он может использовать:
Разрешите коннекторы
PUT /agents/{id}/connectors задаёт, какие ключи коннекторов агент может вызывать (wildberries, ozon, …). Это решает, какие инструменты у него есть. Коннектор, который агенту не разрешён, просто отсутствует в его наборе инструментов.
Выдайте учётные данные
POST /agents/{id}/grants выдаёт агенту конкретный подключённый аккаунт с опциональными scope на чтение/запись. Это решает, какие аккаунты он может использовать — разрешённый коннектор без выданного аккаунта всё равно не вернёт данные.
Агент работает в рамках выдач
В момент исполнения агент дотягивается только до разрешённых коннекторов и выданных аккаунтов; всё остальное вне области. Отозвать — удалив грант.
Полный флоу выдачи — в Agents API.
FAQ
Какие схемы авторизации используют коннекторы?
Одну из трёх, объявленную для каждого сервиса — credentials (API-ключ, токен или basic), popup_oauth (OAuth во всплывающем окне) и device_code (подтверждение на сайте провайдера по короткому коду). Транспорт, прикрепляющий секрет к каждому запросу, — это отдельная ось, которой занимается сам коннектор.
Как хранятся учётные данные?
Подключённые учётные данные шифруются при хранении (Fernet) и хранятся для каждого пользователя. Ассистент никогда не отдаёт сырой секрет; в момент исполнения он подбирает и расшифровывает данные для адресуемого аккаунта.
Может ли один сервис держать несколько аккаунтов?
Да. Один сервис может держать несколько подключённых аккаунтов — несколько кабинетов Ozon, два продавца WB. Каждый — это адресуемый instance; нацельтесь на один через instance_id или суффикс сервиса, например ozon:Top Zip.
Как агент получает доступ к коннектору и его учётным данным?
В два слоя. PUT /agents/{id}/connectors задаёт, какие ключи коннекторов агент может вызывать (какие у него инструменты). POST /agents/{id}/grants выдаёт конкретный подключённый аккаунт с опциональными scope на чтение/запись (какие аккаунты он может использовать). Агент дотягивается только до того, что вы явно выдали.
Частые вопросы
Какие схемы авторизации используют коннекторы?
Одну из трёх, объявленную для каждого сервиса — credentials (API-ключ, токен или basic), popup_oauth (OAuth во всплывающем окне) и device_code (подтверждение на сайте провайдера по короткому коду). Транспорт, прикрепляющий секрет к каждому запросу, — это отдельная ось, которой занимается сам коннектор.
Как хранятся учётные данные?
Подключённые учётные данные шифруются при хранении (Fernet) и хранятся для каждого пользователя. Ассистент никогда не отдаёт сырой секрет; в момент исполнения он подбирает и расшифровывает данные для адресуемого аккаунта.
Может ли один сервис держать несколько аккаунтов?
Да. Один сервис может держать несколько подключённых аккаунтов — несколько кабинетов Ozon, два продавца WB. Каждый — это адресуемый instance; нацельтесь на один через instance_id или суффикс сервиса, например ozon:Top Zip.
Как агент получает доступ к коннектору и его учётным данным?
В два слоя. PUT /agents/{id}/connectors задаёт, какие ключи коннекторов агент может вызывать (какие у него инструменты). POST /agents/{id}/grants выдаёт конкретный подключённый аккаунт с опциональными scope на чтение/запись (какие аккаунты он может использовать). Агент дотягивается только до того, что вы явно выдали.