# Ключи и авторизация

Ключ — заголовок `Authorization: Bearer <ключ>`. Нет ключа или он неверный —
`401 invalid_api_key`.

## Два вида ключей

| Ключ | Начинается с | Что делает |
|---|---|---|
| API-ключ | `sk_` | запускает модели: чат, генерации, задачи, файлы |
| Ключ управления | `mk_` | ведёт аккаунт: баланс, история, расходы, выдача API-ключей, настройки — [Ключ управления](https://souz.ai/docs/management-key.md) |

Ключ не того вида — `403 forbidden` с `detail[].reason` `requires_api_key` или
`requires_management_key`. Исключение — `GET /v1/usage/{id}`: API-ключ читает в нём
запросы, отправленные этим ключом, без предела частоты; запрос другого ключа — `404`.

API-ключ создаёт любой участник аккаунта, кроме наблюдателя (кабинет, «API-ключи»), — себе:
траты ключа идут в его лимит, все ключи тратят общий баланс аккаунта. Секрет повторно
открывает только тот, кто создал ключ: в кабинете или `GET /v1/keys/{id}/secret` своим
ключом управления; остальным — `403` с `detail[].reason: "not_key_author"`. В списке ключей
вместо секрета — подсказка `secret_hint`: приставка, первые 4 и последние 4 знака
(`sk_9f3a…c1d2`).

## Ключ — только на сервере

- Храните ключ на своём сервере в переменной окружения (`SOUZ_API_KEY`), не в коде браузера
  или мобильного приложения, не в логах и не в репозитории. В репозиторий — `.env.example`
  с пустым значением: `SOUZ_API_KEY=`.
- Браузер к `api.souz.ai` напрямую не обращается: CORS у API нет, запрос из страницы
  браузер заблокирует. Фронтенд вызывает ваш сервер, сервер — Souz API.
- Ключ утёк — отзовите его в кабинете («API-ключи») и выпустите новый.

## Что можно без ключа

Каталог (`GET /v1/models`, `GET /v1/models/{id}`, `/stats`, `/channels`, `GET /v1/channels`),
превью роутинга (`POST /v1/models/{id}/routing/preview`), состояние сервиса
(`GET /v1/status`, [Плановые работы](https://souz.ai/docs/errors.md#плановые-работы--503-maintenance)) и документы: `/`,
`/openapi.yaml`, `/openapi.json`, `/llms.txt`, `/llms-full.txt`.

## Сам ключ — `GET /v1/key`

Настройки ключа запроса (схема `APIKey`): потолок трат (`spend_limit`), его период
(`spend_limit_reset`), расход (`spent`), пресет и потолок цены по умолчанию, каналы по
моделям (`routing_options`), сроки хранения (`retention`) и режим без хранения (`no_store`).

```bash
curl https://api.souz.ai/v1/key -H "Authorization: Bearer $SOUZ_API_KEY"
```

## Потолок трат ключа

Потолок ключа — на всё время, в день или в месяц; у участника — общий лимит на все его
ключи. Исчерпан — `402 key_spend_limit_exceeded` или `402 member_spend_limit_exceeded`, без
списания ([Лимиты](https://souz.ai/docs/limits.md)). Ключ субагенту с дневным потолком создаёт и отзывает
[ключ управления](https://souz.ai/docs/management-key.md).

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.