# Ключ и права

> Выпуск ключа для REST API Строфи, набор прав, потолки траты на ключ, передача ключа в запросе, отзыв и проверка состояния счёта.

Источник: https://strophe.app/docs/product/developers/authentication
Обновлено: 2026-08-02

Каждый запрос к API предъявляет ключ. Ключ выпускается в настройках, живёт до отзыва и несёт при себе набор прав и потолки траты — то есть определяет не только «можно ли», но и «на сколько».

## Выпуск ключа

Ключи лежат в настройках, раздел «Интеграции». Как открыть настройки, описано в статье [Настройки](https://strophe.app/docs/product/account/settings).

При выпуске задаются три вещи:

- **Название** — по нему ключ отличают в списке. В запросах не участвует.
- **Права** — что этим ключом разрешено делать.
- **Потолки траты** — сколько кредитов ключ вправе потратить.

Полное значение ключа показывается один раз, сразу после выпуска. Дальше в списке видна только начальная часть — по ней ключ узнают, но восстановить из неё ничего нельзя. Потеряли — выпускайте новый и отзывайте старый.

## Права

Право выдаётся под задачу, а не «на всё»: ключ витрины, показывающей баланс, не должен уметь тратить деньги.

- `catalog:read` — читать каталог моделей и машинную спеку.
- `generations:read` — смотреть состояние генерации, историю и предварительную оценку стоимости.
- `generations:write` — запускать и отменять генерации.
- `files:write` — загружать входные файлы.
- `account:read` — читать состояние счёта.
- `mcp` — подключение агента по протоколу MCP. К REST отношения не имеет и его ручек не открывает.

Запрос с ключом, у которого нужного права нет, получает отказ `insufficient_scope` со статусом 403. Права ключа видны в ответе `GET /api/v1/account`.

## Потолки траты

У ключа два независимых потолка, оба необязательные.

**Суточный** ограничивает трату за календарные сутки по UTC. Счётчик считает и уже списанное, и то, что удерживают идущие генерации; обнуляется он сам.

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

Оба потолка меняются в настройках ключа. Запрос, упёршийся в потолок, получает отказ `spend_limit_exceeded`; поле `details.limitKind` называет, какой именно потолок задет, а у суточного там же лежит момент обнуления.

Потолки — не то же самое, что баланс. Их назначение — ограничить ущерб от ключа, отданного чужой программе: без них ошибка в её коде стоит ровно столько, сколько лежит на счету.

## Передача ключа

Ключ передаётся заголовком `Authorization` в схеме Bearer:

```bash
curl https://strophe.app/api/v1/families \
  -H "Authorization: Bearer <ваш ключ>"
```

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

Запрос без ключа получает 401 `unauthorized`, с отозванным или несуществующим — 401 `invalid_token`. В обоих случаях в ответе есть заголовок `WWW-Authenticate` — по нему клиент понимает, что чинить нужно именно учётные данные, а не запрос.

## Состояние счёта

Сколько можно потратить прямо сейчас, отвечает `GET /api/v1/account` под правом `account:read`:

```bash
curl https://strophe.app/api/v1/account \
  -H "Authorization: Bearer <ваш ключ>"
```

В ответе — доступные кредиты, состояние команды и потолки предъявленного ключа вместе с потраченным за текущие сутки. Именно предъявленного: у каждого ключа потолки свои, и программа видит те, под которыми работает сама.

Отдельного «баланса» в ответе нет намеренно. Полностью занятый идущими генерациями счёт выглядел бы полным, и программа запустила бы работу, которой не на что выполниться.

## Отзыв

Ключ отзывается в том же разделе настроек. Отзыв мгновенный: следующий запрос с этим ключом получит 401.

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

Ссылки на результаты, выданные этим ключом, перестают работать вместе с ним. Это относится и к ссылкам, полученным раньше: они живут ровно столько, сколько живёт ключ, которым были выданы.