> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Обзор API Yahont

**Почти любая функция Yahont доступна через API Yahont.**

API Yahont построены на принципах REST с форматом запросов и ответов JSON.
Все конечные точки требуют аутентификации и следуют достаточно единообразным шаблонам.

Отправляйте запросы API на адрес `https://your-yahont-domain.com/api`. После запуска Yahont Cloud добавим его адрес.

> [!NOTE]
>
> Yahont следует [SemVer 2.0.0](https://semver.org/). Несовместимые изменения обозначаются увеличением мажорной версии.

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

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

```bash theme={null}
curl -H "Authorization: Bearer <token>" \
  https://your-yahont-domain.com/api/me/permissions
```

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

### Ключи API

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

У сервисного аккаунта нет собственных прав. Его доступ определяется **группами**,
которые вы назначаете ему при создании ключа.

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

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

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

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

Инструкции по настройке см. в разделе [Сервисные аккаунты](/admins/user_management/api_keys).

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

Персональные токены доступа (PAT) позволяют пользователю аутентифицировать запросы API от своего имени.

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

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

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

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

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

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

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

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

## Права

Каждая страница конечной точки в [справочнике API](/developers/api_reference/chat/get_chat_session)
указывает необходимое право. Права определяются группами, в которых состоит пользователь или сервисный аккаунт:
`basic` — из группы Basic, в которую входит каждый пользователь, и `admin` — из группы Admin,
которая проходит любую проверку.

> [!NOTE]
>
> О том, как работают группы, права групп и менеджеры групп, см.
> в разделе [Как устроены права](/admins/permissions/understanding_permissions).

Страницы конечных точек и `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` возвращает разрешённые права вызывающего пользователя:

```bash theme={null}
curl -H "Authorization: Bearer <token>" \
  https://your-yahont-domain.com/api/me/permissions
```

```json theme={null}
{
  "permissions": ["basic", "manage:connectors", "read:chat", "read:connectors", "..."],
  "is_manager": false,
  "managed_group_ids": []
}
```

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

```json theme={null}
{
  "error_code": "INSUFFICIENT_PERMISSIONS",
  "detail": "You do not have the required permissions for this action."
}
```

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

В [справочнике API](/developers/api_reference/chat/get_chat_session)
мы подобрали подмножество полезных конечных точек API Yahont. На каждой странице есть примеры запросов.
Можно также пройти одно из наших [руководств](/developers/guides/chat_new_guide).

Все конечные точки API Yahont можно найти во встроенном обозревателе OpenAPI:

`https://your-yahont-domain.com/api/docs`

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

> **[Основные понятия](/developers/core_concepts)**
>
> Изучите основные понятия и терминологию работы с API Yahont

> **[Руководство: отправка сообщения чата](/developers/guides/chat_new_guide)**
>
> Простой пример программной отправки сообщения


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.