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

Ключ для скрипта или агента, который ведёт аккаунт: баланс, расходы, выдача и отзыв обычных ключей. Создают его владелец и администратор себе в кабинете («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 по его ключу управления:

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):

Терминал

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"}'