Воркспейсы и баланс

Воркспейс — это единица изоляции и биллинга в Runne Pass. Он владеет балансом, API-ключами, квотой и историей использования.

Создание воркспейса

curl -b cookies.txt -X POST https://api.runne.run/v1/workspaces \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-app"}'

name обязателен (мин. 1 символ). Ответ (HTTP 201):

{
  "id": "0191…",
  "customer_id": "0191…",
  "name": "my-app",
  "balance": "0",
  "currency": "RUB",
  "status": "active",
  "created_at": "…",
  "updated_at": "…"
}

Воркспейс создаётся с balance: "0", currency: "RUB" и status: "active". Создание также вставляет строку членства owner для клиента — всё в одной транзакции.

Список воркспейсов

curl -b cookies.txt https://api.runne.run/v1/workspaces

{ "workspaces": [ { "id": "0191…", "customer_id": "0191…", "name": "my-app", "balance": "0", "currency": "RUB", "status": "active", "created_at": "…", "updated_at": "…" } ] }

Возвращаются только воркспейсы, принадлежащие текущему клиенту.

Владение и защита от IDOR

Каждый эндпоинт в разрезе воркспейса определяет клиента из сессии и проверяет, что запрошенный workspace_id принадлежит этому клиенту:

workspace.customer_id == session.customer_id

Несовпадение возвращает 403 (или 404 на некоторых эндпоинтах). Значения workspace_id не в формате UUID трактуются как «не принадлежит», а не как ошибка приведения типа в базе. Так как владение проверяется при каждой мутации, вы не можете прочитать или изменить чужой воркспейс, подбирая идентификаторы.

Баланс

Баланс хранится как десятичная строка (в токенах) в строке воркспейса, а не как число с плавающей точкой. Обращайтесь с ним как с непрозрачным текстом; никогда не приводите его к float.

curl -b cookies.txt https://api.runne.run/v1/workspaces/WORKSPACE_ID/balance

{ "balance": "0", "updated_at": "…" }

Те же данные доступны через поверхность API-ключей на GET /v1/balance (скоуп balance:read), который дополнительно возвращает currency.

Как меняется баланс

• Зачисление (credit) — пополнение через успешный платёж (вебхук).
• Резервирование / расчёт / возврат — chat completions.
• Корректировка (adjustment) — правка, инициированная администратором.
• Списание (debit) — покрытие дефицита, когда запрос обошёлся дороже оценки.

Каждое изменение пишет строку реестра — см. Архитектуру и Ошибки про поведение 402 insufficient_balance.

Статус воркспейса

Статус	Значение
active	Обычная работа
suspended	Блокирует запросы по API-ключу (403) и приостанавливает доступ по сессии; устанавливается автоматически, когда дефицит нельзя списать, либо администратором
archived	Выведен из эксплуатации

Приостановленный воркспейс (или приостановленный клиент) отклоняется шлюзом до обработки любого запроса.

Связанное

• API-ключи — ключи принадлежат воркспейсу.
• Лимиты и квоты — квота задаётся в разрезе воркспейса.
• Платежи и YooKassa — пополнение воркспейса.