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

# Получите API-ключ

> Создавайте, обновляйте и удаляйте ключи на странице «Интеграции» агента.

Ключами управляют в приложении Chattler: на странице **Интеграции** агента, в карточке **Доступ по API**. Ни один вызов API ключ не создаёт.

## Создать ключ

<Steps>
  <Step title="Откройте агента">
    В приложении откройте агента, к которому хотите дать доступ, и перейдите на его страницу **Интеграции**.
  </Step>

  <Step title="Добавьте ключ в карточке «Доступ по API»">
    Дайте ключу название и выберите доступ:

    * `read-only`: список диалогов и чтение сообщений.
    * `full`: всё перечисленное плюс эндпоинты чата.
  </Step>

  <Step title="Сразу скопируйте ключ">
    Ключ целиком показывается **один раз**, сразу после создания. Он выглядит так:

    ```text theme={null}
    cht_live_<key_id>.<secret>
    ```

    Аутентифицирует только секретная часть. Часть `key_id` публичная и служит идентификатором ключа везде в интерфейсе. Если потеряли секрет — обновите ключ.
  </Step>
</Steps>

## Обновить ключ

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

## Удалить ключ

Удаление убирает ключ. С этого момента каждый запрос с ним завершается `401 invalid_api_key` — неотличимо от ключа, которого никогда не было. Его диалоги и история запросов остаются доступными в интерфейсе. Удаление нельзя отменить; вместо этого создайте новый ключ.

<Warning>
  **Никогда не встраивайте ключ в браузерную сборку, мобильное приложение или любой клиент, который вы не контролируете.** Ключ — долгоживущий секрет владельца, который тратит его баланс. Вызывайте API со своего бэкенда и обновляйте ключ, как только заподозрили утечку.
</Warning>

## Аутентификация по ключу

Принимается только заголовок `Authorization` со схемой `Bearer`. Учётные данные в строке запроса игнорируются; токен интерфейса и заголовок `Browser-ID` не участвуют.

```http theme={null}
Authorization: Bearer cht_live_<key_id>.<secret>
```

Ключ привязан к одному агенту. Использование его с другим `{agent_id}` возвращает `403 agent_mismatch`.

## Статистика

Использование в карточке «Доступ по API» не показывается. Откройте страницу **Статистика** агента и выберите ключ в фильтре **Интеграция**; каждый ключ представлен там как отдельная интеграция. Страница показывает по каждому ключу и за каждый день по UTC число запросов, успешные и неуспешные запросы, долю ошибок, среднюю задержку и p95, уникальных пользователей, активные диалоги, токены и списанную сумму, а также разбивку по эндпоинтам, HTTP-статусам и кодам ошибок. Стоимость у провайдера никогда не раскрывается; показанная сумма — то, что списано с баланса.