Policy Rules, Virtual Groups и Systems

Концепция: Policy Rules.

Требуется Bearer-токен. Endpoints изменения — роли owner или admin, если не указано иное.

PolicyRule — общая модель

clientSubject.type: organization, api_key, system, member, virtual_group.

Модули (нужен хотя бы один):

• access: allowedModels[], allowedProviders[], deniedModels[]
• budget: limitRub, resetInterval (daily / weekly / monthly), scope
• content: pii, content, customPatterns[], promptInjection, mode (enforce / observe)
• rateLimit: rpm, tpm

content.customPatterns[]: { "pattern": "regex", "action": "block|mask|warn", "label": "…" }

content.promptInjection: { "enabled": true, "action": "warn|mask|block", "patterns": ["…"] } — если patterns пуст, применяются встроенные regex.

Справочник всех встроенных regex (PII, injection) и ограничений синтаксиса: Policy Rules — проверка контента.

Tenant API поддерживает scope-уровни 1–4 (client × provider × model). Правила одного scope (client + provider + model) уникальны — дубликат вернёт 409 Conflict.

Для личного аккаунта (accountType: personal) доступны только clientSubject типов organization и api_key.

GET /api/organizations/{orgId}/policy/rules

Список policy rules организации (включая глобальные правила платформы, применимые к org).

curl -s https://api.example.com/api/organizations/org_abc/policy/rules \
  -H "Authorization: Bearer <token>"

Ответ 200: массив PolicyRule.

POST /api/organizations/{orgId}/policy/rules

Создать правило.

curl -s -X POST https://api.example.com/api/organizations/org_abc/policy/rules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSubject": {"type": "organization", "id": "org_abc"},
    "access": {"allowedModels": ["openai/gpt-4o-mini"]},
    "budget": {"limitRub": 50000, "resetInterval": "monthly", "scope": "organization"}
  }'

Ответ 201: созданный PolicyRule.

Ошибки: 400 — валидация; 409 — правило с таким scope уже существует.

Аудит: policy_rule.created.

PATCH /api/organizations/{orgId}/policy/rules/{ruleId}

Обновить правило (полное тело правила, id берётся из URL).

Ответ 200: обновлённый PolicyRule.

Аудит: policy_rule.updated.

DELETE /api/organizations/{orgId}/policy/rules/{ruleId}

Удалить правило.

Ответ 204: без тела.

Аудит: policy_rule.deleted.

GET /api/organizations/{orgId}/policy/form-options

Справочник для форм: клиенты, модели каталога (при providerSlug).

curl -s "https://api.example.com/api/organizations/org_abc/policy/form-options?providerSlug=openai" \
  -H "Authorization: Bearer <token>"

Ответ 200:

{
  "organizationId": "org_abc",
  "providerSlug": "openai",
  "clientSubjects": [
    {"type": "organization", "id": "org_abc", "label": "ООО Пример", "group": "organization"}
  ],
  "catalogModels": [
    {"catalogModelId": "openai/gpt-4o", "label": "GPT-4o", "providerSlug": "openai"}
  ]
}

POST /api/organizations/{orgId}/policy/evaluate

Проверить текст по content-модулям всех правил организации (без учёта client tier конкретного ключа).

Тело:

curl -s -X POST https://api.example.com/api/organizations/org_abc/policy/evaluate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text":"contact me at user@example.com"}'

Ответ 200 — FilterEvaluation:

{
  "blocked": true,
  "maskedText": "",
  "matches": [
    {"kind": "pii", "type": "email", "action": "block", "label": "email"}
  ]
}

POST /api/organizations/{orgId}/policy/preview

Предпросмотр access-политики для API-ключа или системы: какие модели разрешены после collect + merge.

Тело:

curl -s -X POST https://api.example.com/api/organizations/org_abc/policy/preview \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId":"key_xyz","catalogModelIds":["openai/gpt-4o","openai/gpt-4.1"]}'

Ответ 200:

{
  "apiKeyId": "key_xyz",
  "models": [
    {"catalogModelId": "openai/gpt-4o", "allowed": true},
    {"catalogModelId": "openai/gpt-4.1", "allowed": false, "reason": "модель вне разрешённого списка"}
  ]
}

Virtual Groups

Виртуальная группа объединяет участников (memberIds) и системы (systemIds). API-ключи в группу не добавляются — ключ наследует группы через владельца или systemId.

Доступно только для бизнес-организаций (accountType: business). Список — любой участник org; создание/изменение — owner / admin.

GET /api/organizations/{orgId}/virtual-groups

Ответ 200: массив VirtualGroup.

POST /api/organizations/{orgId}/virtual-groups

Ответ 201: VirtualGroup со status: active.

Аудит: virtual_group.created.

PATCH /api/organizations/{orgId}/virtual-groups/{groupId}

Частичное обновление: name, description, status (active / archived), memberIds, systemIds.

Ответ 200: обновлённая группа.

Аудит: virtual_group.updated.

DELETE /api/organizations/{orgId}/virtual-groups/{groupId}

Архивирует группу (status: archived).

Ответ 204: без тела.

Аудит: virtual_group.archived.

Client Systems (IS / Agent)

Информационные системы и агенты для привязки API-ключей и policy rules на tier system.

Только бизнес-организации. Изменение — owner / admin.

GET /api/organizations/{orgId}/systems

Ответ 200: массив ClientSystem.

POST /api/organizations/{orgId}/systems

Ответ 201:

{
  "id": "sys_001",
  "organizationId": "org_abc",
  "slug": "crm-backend",
  "name": "CRM Backend",
  "kind": "system",
  "status": "active",
  "createdAt": "2026-06-18T12:00:00Z",
  "updatedAt": "2026-06-18T12:00:00Z"
}

Ошибки 400: дубликат slug, некорректный kind.

Связь с overview

GET /api/overview возвращает policyRuleCount — число правил org (без полного списка). Полный CRUD — через endpoints выше.

Что дальше

• Policy Rules (концепция)
• Лимиты и квоты
• API-ключи