Обзор и аутентификация

Почти любая функция Yahont доступна через API Yahont. API Yahont построены на принципах REST с форматом запросов и ответов JSON. Все конечные точки требуют аутентификации и следуют достаточно единообразным шаблонам. Отправляйте запросы API на адрес https://your-yahont-domain.com/api. После запуска Yahont Cloud добавим его адрес.

Yahont следует SemVer 2.0.0. Несовместимые изменения обозначаются увеличением мажорной версии.

Аутентификация

Каждый запрос аутентифицируется токеном Bearer в заголовке Authorization:

curl -H "Authorization: Bearer <token>" \
  https://your-yahont-domain.com/api/me/permissions

В Yahont есть два вида токенов. Ключ API принадлежит сервисному аккаунту. Персональный токен доступа принадлежит вам.

Ключи API

Ключи API создаются администраторами в панели администратора. Каждый ключ существует в Yahont как отдельный пользователь — сервисный аккаунт, поэтому можно отслеживать активность, держать сессии чата приватными и ограничивать ресурсы конкретным ключом. У сервисного аккаунта нет собственных прав. Его доступ определяется группами, которые вы назначаете ему при создании ключа.

Назначенные группы	Что может ключ
Нет	Только чат. Он может создавать сессии и отправлять сообщения, но не может искать и не имеет доступа ни к одной конечной точке администратора.
Basic	Чат, поиск, проекты и собственные агенты.
Admin	Все конечные точки, включая те, что начинаются с `admin/`.
Пользовательская группа	Всё, что даёт эта группа. Например, группа с правом Управление коннекторами и наборами документов открывает конечные точки коннекторов и наборов документов.

Права складываются. Ключ в нескольких группах получает объединение их прав.

Ключ в группе Admin имеет неограниченный доступ к вашему инстансу Yahont. Лучше использовать группу, которая даёт только права, нужные вашей интеграции.

Пользовательские группы и настраиваемые права групп — функция Enterprise Edition.

Инструкции по настройке см. в разделе Сервисные аккаунты.

Персональные токены доступа

Персональные токены доступа (PAT) позволяют пользователю аутентифицировать запросы API от своего имени. Чтобы создать токен, откройте Настройки > Аккаунты и доступ и нажмите Создать новый токен. Задайте название, выберите срок действия (7 дней, 30 дней, 365 дней или бессрочный) и выберите его права:

Права	Поведение
Полный доступ	Токен наследует все ваши права.
Ограниченный доступ	Токен ограничен выбранными вами областями.

Ограниченный токен может использовать следующие области:

Область	Право	Что разрешает
Поиск — чтение	`read:search`	Использовать конечные точки поиска и веб-поиска.
Чат — чтение	`read:chat`	Просматривать сессии и сообщения чата.
Чат — запись	`write:chat`	Создавать сессии и отправлять сообщения. Включает «Чат — чтение».

Области только сужают доступ. Ограниченный токен получает выбранные вами области и ваши собственные права, но никогда не больше, чем можете вы сами. Ограниченный токен также отклоняется на любой конечной точке вне его областей, даже если вы можете открыть её в браузере.

Для создания токена нужно право Создание токена доступа пользователя, которое администратор выдаёт группе. У администраторов оно есть всегда.

Токен показывается только один раз при создании. Сразу скопируйте его и надёжно сохраните.

Вы можете в любой момент просмотреть, проверить и отозвать свои токены в Настройки > Аккаунты и доступ.

Права

Каждая страница конечной точки в справочнике API указывает необходимое право. Права определяются группами, в которых состоит пользователь или сервисный аккаунт: basic — из группы Basic, в которую входит каждый пользователь, и admin — из группы Admin, которая проходит любую проверку.

О том, как работают группы, права групп и менеджеры групп, см. в разделе Как устроены права.

Страницы конечных точек и GET /me/permissions определяют право по его значению. Каждое значение соответствует праву, которое администратор выдаёт группе в панели администратора:

Панель администратора	Право
Управление LLM	`manage:llms`
Управление коннекторами и наборами документов	`manage:connectors`, `manage:document_sets`
Управление действиями	`manage:actions`
Управление группами	`manage:user_groups`
Управление сервисными аккаунтами	`manage:service_account_api_keys`
Управление ботами Slack и Discord	`manage:bots`
Создание агентов	`add:agents`
Управление агентами	`manage:agents`
Просмотр аналитики агентов	`read:agent_analytics`
Просмотр истории запросов (Enterprise Edition)	`read:query_history`
Создание токена доступа пользователя	`create:user_api_keys`

Право на управление также даёт нужные ему права на чтение — manage:connectors включает read:connectors — поэтому у вызывающего пользователя оказывается больше прав, чем было выдано.

Проверка возможностей токена

GET /me/permissions возвращает разрешённые права вызывающего пользователя:

curl -H "Authorization: Bearer <token>" \
  https://your-yahont-domain.com/api/me/permissions

{
  "permissions": ["basic", "manage:connectors", "read:chat", "read:connectors", "..."],
  "is_manager": false,
  "managed_group_ids": []
}

Запрос, не прошедший проверку прав, возвращает 403:

{
  "error_code": "INSUFFICIENT_PERMISSIONS",
  "detail": "You do not have the required permissions for this action."
}

Справочник API

В справочнике API мы подобрали подмножество полезных конечных точек API Yahont. На каждой странице есть примеры запросов. Можно также пройти одно из наших руководств. Все конечные точки API Yahont можно найти во встроенном обозревателе OpenAPI: https://your-yahont-domain.com/api/docs

Дальнейшие шаги

Основные понятия

Изучите основные понятия и терминологию работы с API Yahont

Руководство: отправка сообщения чата

Простой пример программной отправки сообщения

Начало работы

Руководства и примеры

Справочник API

Разное

Аутентификация

Ключи API

Персональные токены доступа

Права

Проверка возможностей токена

Справочник API

Дальнейшие шаги

Основные понятия

Руководство: отправка сообщения чата

​Аутентификация

​Ключи API

​Персональные токены доступа

​Права

​Проверка возможностей токена

​Справочник API

​Дальнейшие шаги

Основные понятия

Руководство: отправка сообщения чата

Аутентификация

Ключи API

Персональные токены доступа

Права

Проверка возможностей токена

Справочник API

Дальнейшие шаги