# Ключ управления

Ключ для скрипта или агента, который ведёт аккаунт: баланс, расходы, выдача и отзыв обычных
ключей. Создают его владелец и администратор себе в кабинете («API-ключи»); секрет
начинается с `mk_`. Потолка трат нет — ключ ничего не тратит.

## Что он может

**То же, что держатель видит и может в кабинете**: роль, лимит, цифры. Разработчик видит и
меняет только свои ключи и запросы, наблюдатель только смотрит. Смена роли держателя
действует сразу; держателя перевели в наблюдатели или убрали — ключ отозван вместе с его
ключами.

| Метод | Что делает |
|---|---|
| `GET /v1/auth/me` | кто держатель: роль, лимит трат с расходом и остатком |
| `GET /v1/balance`, `GET /v1/balance/history` | баланс и история операций |
| `GET /v1/usage`, `GET /v1/usage/summary`, `GET /v1/usage/{id}` | запросы и расходы |
| `GET` и `POST /v1/keys`, `PATCH` и `DELETE /v1/keys/{id}`, `GET /v1/keys/{id}/secret` | обычные ключи |
| `GET /v1/settings`, `PATCH /v1/settings` | пресет, потолок цены, адрес вебхука, каналы по моделям, режим без хранения; менять — с ролью разработчика или выше |
| `GET /v1/webhooks/secret`, `POST /v1/webhooks/secret/rotate` | секрет подписи вебхуков; с ролью разработчика или выше |

`GET /v1/key` отвечает и ему: `kind: "management"`, потолка трат нет. У музыкальных
запросов в `GET /v1/usage` — действие (`action`) и версия (`model_version`). У удавшейся
генерации в строке — `result`: файл результата со ссылкой, как в `GET /v1/usage/{id}`.
`?source=playground` — только запросы из плейграунда.

## Чего он не может

- Модели не запускает: генерации, задачи и файлы отвечают `403 forbidden` с
  `detail[].reason: "requires_api_key"`; обычный API-ключ на методах аккаунта — `403` с
  `requires_management_key`, кроме `GET /v1/usage/{id}` по своим запросам.
- Только в кабинете: участники, оценки пресетов, профиль и вход, выпуск ключей управления
  — `403` с `cabinet_only`. Секрет чужого ключа — `403` с `not_key_author`. Роли не хватает — `403` с `insufficient_role`, в `allowed` —
  роли, которым можно.
- Запросов на чтение (`GET`) — до 1200 в минуту на ключ, изменений — до 300; выпуск и
  отзыв ключей и настройки — ещё и свои пределы в час («Лимиты»). Действия через ключ попадают в журнал аккаунта от имени
  держателя с пометкой, через какой ключ.

## Пример: кто я и ключ для субагента

Держатель — администратор с лимитом; `GET /v1/auth/me` по его ключу управления:

<!-- openapi: #/components/schemas/MeResponse -->
```json
{
  "id": "mem_1a2b3c4d5e6f7890",
  "email": "ivan@example.com",
  "telegram_username": "",
  "name": "Иван Петров",
  "avatar_url": null,
  "role": "admin",
  "account": {"id": "user_1a2b3c4d5e6f7890", "name": "Acme", "number": "К 482 МТ · 77", "blocked": false, "has_balance": true},
  "spend_limit": {"amount_micro": 5000000000, "reset": "monthly", "spent_micro": 1250000000, "remaining_micro": 3750000000}
}
```

Ключ субагенту с потолком 500 ₽ в день — `POST /v1/keys` (схема `CreateAPIKeyRequest`; ключ
его, траты — в его лимит; секрет в ответе, повторно — `GET /v1/keys/{id}/secret`):

```bash
curl https://api.souz.ai/v1/keys \
  -H "Authorization: Bearer $SOUZ_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "sub-agent", "spend_limit_micro": 500000000, "spend_limit_reset": "daily"}'
```

---

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