Management API

Management Key

Management API позволяет создавать API-ключи, управлять пространствами и их бюджетами без сессии кабинета. Владелец или администратор создаёт Management Key в разделе Management Keys выбранного аккаунта.

Ключ действует во всех пространствах этого аккаунта. Организации, приглашения и роли управляются в кабинете; порядок работы описан в разделе Организации.

Все пути ниже используют базовый адрес https://gorouter.ru/api/v1 и заголовок Authorization: Bearer $GOROUTER_MANAGEMENT_KEY.

Создание API-ключа

curl https://gorouter.ru/api/v1/keys \
  -X POST \
  -H "Authorization: Bearer $GOROUTER_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "limit": 500,
    "limit_reset": "monthly"
  }'

Без workspace_id ключ создаётся в Default, без member_id — для создателя Management Key.

• name — название до 80 символов.
• limit — лимит расходов в RUB или null.
• limit_reset — daily, weekly, monthly или null.
• expires_at — будущая дата UTC в ISO 8601 или null.
• disabled изменяется через PATCH /keys/{hash}.
• sensitive_data включает защиту чувствительных данных для конкретного inference-ключа.
• workspace_id — ID пространства этого аккаунта.
• member_id — ID пользователя, состоящего в аккаунте и имеющего доступ к пространству.
• privacy задаёт ограничения провайдеров для ключа, не ослабляя правила аккаунта и пространства.

При создании поле data.key содержит секрет и больше не возвращается. Для дальнейших операций используйте идентификатор data.hash.

GET /keys поддерживает workspace_id, member_id, offset, limit и include_disabled. Без выбора пространства и участника возвращаются ключи создателя Management Key в Default. GET и PATCH /keys/{hash} позволяют просмотреть и изменить ключ, DELETE отзывает его и возвращает { "deleted": true }.

Пространства

Для создания пространства с дневным и месячным бюджетами:

curl https://gorouter.ru/api/v1/workspaces \
  -X POST \
  -H "Authorization: Bearer $GOROUTER_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "slug": "production",
    "budgets": [
      { "interval": "daily", "limit_rub": "1000" },
      { "interval": "monthly", "limit_rub": "10000" }
    ]
  }'

Ответ содержит пространство в data. Используйте его id как workspace_id при создании ключей и в путях управления пространством.

• GET /workspaces — список активных пространств.
• GET, PATCH, DELETE /workspaces/{id} — просмотреть, изменить, архивировать. Архивирование отзывает ключи, сохраняя расходы; Default архивировать нельзя.

name и slug — до 80 символов. Slug содержит строчные латинские буквы, цифры и дефисы. Необязательное description — до 500 символов.

Бюджеты

• GET, PUT, DELETE /workspaces/{id}/budgets/{interval} — бюджет пространства.
• GET, PUT, DELETE /workspaces/{id}/members/{member_id}/budgets/{interval} — общий бюджет ключей и чата участника внутри пространства.

PUT принимает { "limit_rub": "1000" }. Суммы — в рублях, периоды — daily, weekly, monthly, lifetime. Заданные лимиты должны строго возрастать в этом порядке. Периоды календарные, UTC, неделя начинается в понедельник.

Изменение и повторное создание бюджета не сбрасывают расходы. Учитываются активные резервы; итог уже начатого запроса может превысить лимит и заблокировать новые запросы. Подробнее — бюджеты пространства и участника.

Ошибки и ограничения

• Management Keys создаются и отзываются только через кабинет и не подходят для вызова моделей.
• Неописанные параметры возвращают 400 unsupported_parameter.
• Операции изолированы аккаунтом: чужой hash возвращает 404 key_not_found.