Войти

Ключ и права

Обновлено

Скачать Markdown

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

Выпуск ключа

Ключи лежат в настройках, раздел «Интеграции». Как открыть настройки, описано в статье Настройки.

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

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

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

Права

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

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

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

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

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

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

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

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

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

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

Отзыв

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

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

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