Организации и RBAC

Обзор

Организации позволяют командам совместно использовать API-ключи, квоты и биллинг. Каждая организация имеет собственный кошелёк, лимиты расходов и набор участников с разными ролями.

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

Создание организации

Для создания организации отправьте POST /organizations:

{
  "name": "Моя компания",
  "inn": "1234567890",     // Необязательно, ИНН (10 или 12 цифр)
  "kpp": "123456789",      // Необязательно, КПП (9 цифр)
  "billingEmail": "pay@company.ru"  // Необязательно
}

Создатель автоматически становится owner организации. Поле inn становится неизменяемым после первого платежа.

Роли и права

Каждый участник организации имеет одну из трёх ролей. Набор разрешений определяется ролью:

Иерархия действий

• owner может изменять роли всех участников, приостанавливать и удалять любого (включая admin)
• admin может управлять engineer-участниками, но не может изменять другого admin или owner
• engineer может только использовать API (потреблять квоту)

Workspaces для API-ключей

Workspace разделяет организационные API-ключи, использование и будущие лимиты по проектам или средам. Типовая схема: Development, Staging, Production.

• GET /organizations/:orgId/workspaces — список активных workspaces
• POST /organizations/:orgId/workspaces — создать workspace
• POST /organizations/:orgId/workspaces/:workspaceId/archive — архивировать workspace, кроме default

Если у организации ещё нет workspace, default workspace создаётся автоматически при первом запросе списка. Организационный API-ключ можно привязать к workspace через поле workspaceId, а список ключей можно фильтровать query-параметром workspaceId.

Управление участниками

Приглашение

Отправьте POST /organizations/:orgId/invites с email и ролью:

{
  "email": "user@company.ru",
  "role": "engineer"   // owner | admin | engineer
}

Приглашение действует 7 дней. Только один активный инвайт на email в рамках организации. Если у организации настроены allowedDomains, email должен принадлежать разрешённому домену.

Принятие приглашения

Получатель принимает приглашение через POST /invites/accept с токеном из письма. Email пользователя должен совпадать с email приглашения.

Rate limit: 10 запросов в минуту на IP, 5 попыток в час на email.

Изменение роли

PATCH /organizations/:orgId/members/:memberId/role

Роль ownerнельзя назначить напрямую — используйте передачу владения.

Приостановка и восстановление

• POST /organizations/:orgId/members/:memberId/suspend— приостанавливает доступ участника
• POST /organizations/:orgId/members/:memberId/unsuspend— восстанавливает доступ

Нельзя приостановить owner. Admin не может приостановить другого admin.

Удаление участника

DELETE /organizations/:orgId/members/:memberId

Мягкое удаление (статус removed). Нельзя удалить owner — сначала передайте владение. При удалении участника его расходы начинают списываться с личного кошелька.

Передача владения

POST /organizations/:orgId/transfer-ownership

{
  "targetMemberId": "uuid-нового-владельца"
}

Операция атомарна: текущий owner понижается до admin, целевой участник повышается до owner в одной транзакции с CAS-защитой от конкурентных изменений.

Биллинговый контекст

Для API-запросов биллинговый контекст определяется автоматически: личные ключи списывают средства с кошелька пользователя, организационные ключи — с кошелька организации.

API-ключи организации

Ключи организации привязаны к кошельку организации, а не к персональному аккаунту. Расходы по ключу списываются с организации.

• Максимум 50 активных ключей на организацию
• Создавать и отзывать ключи могут только owner и admin
• Управление: POST /organizations/:orgId/api-keys, POST /organizations/:orgId/api-keys/:id/revoke

Подробнее о формате ключей и авторизации — на странице Аутентификация.

Лимиты и квоты

Организации используют кошелёк и квоты так же, как персональные аккаунты. На ключ организации можно установить ежемесячный лимит расходов (spend limit).

Подробнее о тарифах, квотах и лимитах — на страницах Биллинг и цены и Лимиты запросов.

Статусы участников

Статусы приглашений