Воркспейсы, участники и токены

Воркспейс — это граница тенантности. Всё, что создаёт бот, живёт внутри воркспейса: диалоги, сообщения, события, файлы, строки таблиц, метеринг. Воркспейс платформа выводит из токена, а не из заголовков запроса. Рядом в том же воркспейсе — боты, участники с ролями и выпущенные ключи.

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

Отсюда мультитенантность из коробки. Облако обслуживает много воркспейсов сразу, и код доступа к данным не пересекает их границу: scope приходит из аутентификации, а не из ввода.

Воркспейс как граница

Каждый запрос к API проходит один из двух швов аутентификации. Оба резолвят Authorization: Bearer … в scope тенанта: тройку (воркспейс, владелец, бот). Дальше все обращения к БД фильтруются этим scope.

Главный инвариант: тенант берётся из ключа, никогда из клиентских заголовков. Заголовки x-workspace-id или x-bot-id лишь выбирают сущность среди доступных ключу. Принадлежность перепроверяется по членству в базе. Подставили чужой workspaceId — получите 404, а не доступ. Существование чужого тенанта платформа не раскрывает.

Участники и роли

Участник — это человек-аккаунт в воркспейсе с одной из трёх ролей. Роль платформа резолвит по членству и отдаёт в GET /v1/admin/me вместе со списком воркспейсов.

Матрица прав проверяется на сервере — до хендлера или внутри него.

Создать воркспейс может любой аккаунт: POST /v1/admin/workspaces. Создатель сразу становится owner.

Две оси доступа

Аутентификация идёт по двум параллельным осям. Они не пересекаются и не подменяют друг друга.

• Человеческий вход. Человек входит в консоль через внешний OIDC-провайдер. Консоль получает session-JWT и ходит на human-дерево API (/v1/admin/me, /v1/admin/workspaces/*). Всё скоупится членством человека в воркспейсах.
• Машинный доступ. CLI brt, боты и сервисы предъявляют api-ключ или личный токен. Это отдельная ветка middleware, scope выводится из самого ключа.

Ветку платформа выбирает по форме токена, без угадывания. Префикс brt_pat_ — это PAT-путь. Всё прочее без префикса идёт на верификацию session-JWT. Двусмысленности нет: session-JWT это compact JWS, он начинается с eyJ и префикс нести не может.

Таксономия токенов

Все токены хранятся в базе только как sha256-хеш. Сырое значение ключа или PAT показывается ровно один раз, в ответе на создание, и невосстановимо. Потеряли — выпускайте новый и отзывайте старый. Мягкий отзыв виден следующему же запросу.

printf '%s' "$MY_SECRET" | brt secret set STRIPE_KEY

Как резолвится тенант из токена

• Ключ бота (bf_, per-bot) несёт ненулевой BotID и работает на всех маршрутах, включая привязанные к конкретному боту.
• Личный токен (brt_pat_) на human-дереве действует как аккаунт-владелец. На машинной шине с заголовком x-workspace-id становится воркспейс-скоупным принципалом (BotID=0). Заголовок лишь выбирает воркспейс среди тех, где аккаунт состоит; членство перепроверяется — не член получает 403, отсутствие заголовка — 400.
• Ключ интеграции (bf_, iak) воркспейс-скоупный и несёт BotID=0. Он работает на воркспейс-широких поверхностях (реестр, определения интеграций), но на любом маршруте конкретного бота получает честный 403. Ключ интеграции не может «просочиться» под видом ключа бота.

Проверка через API

Личный токен на human-дереве возвращает ваш аккаунт и все воркспейсы с ролями.

curl https://botruntime.ru/v1/admin/me \
  -H "Authorization: Bearer brt_pat_2f6b…c91a"

{
  "account": {
    "id": "42",
    "email": "ops@example.com"
  },
  "workspaces": [
    { "id": "7", "name": "Acme", "handle": "acme", "role": "owner" },
    { "id": "9", "name": "Beta", "handle": "beta", "role": "member" }
  ]
}

Тот же PAT на машинной шине требует x-workspace-id, чтобы выбрать воркспейс из списка:

curl "https://botruntime.ru/v1/admin/workspaces/7/usages?type=ai_spend" \
  -H "Authorization: Bearer brt_pat_2f6b…c91a" \
  -H "x-workspace-id: 7"

Метеринг и квоты

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

• Метеринг. Расход пишется в append-only леджер meter_event. Основной учитываемый юнит — llm_cost_micro_usd: стоимость LLM в микро-долларах, целочисленные деньги, без float. Расход агрегируется по месяцам и разбивается по ботам (GET /v1/admin/usages/…, /workspaces/{id}/usages/by-bot).
• Квоты. У воркспейса есть лимиты — например, ai_spend, потолок трат на LLM в USD/месяц. Дефолты консервативны; override пишется через PUT /v1/admin/quotas/ai-spend.

У ботов нет собственных ключей LLM-провайдера: модельные вызовы идут через шлюз платформы, где и живут лимиты, метеринг и трейсинг. Трейсы всегда metadata-only: содержимое сообщений, prompt/output и user/session/message IDs не записываются и не экспортируются.

Дальше