Права и роли

В Apiin один каталог прав на всё: API-ключи, OAuth-подключения MCP и роли участников кабинета проверяются одними и теми же правилами. Право называется раздел:действие и открывает конкретный набор операций — не больше и не меньше.

Как устроены права

Чтение и запись разделены. documents:read показывает реестр и PDF, documents:write — создаёт и правит. Запись не даёт чтения: ключу только с documents:write список документов недоступен.
Опасные действия — отдельно. Удаление, отметка подписи и всё, что связано с деньгами, вынесены из *:write: documents:delete, documents:sign, payments:write, counterparties:delete, products:delete. Так менеджер выставляет счета, но не удаляет их, а бухгалтер отмечает оплаты, но не правит документы.
Разделы «только запись». У ассетов, оферт, публичных ссылок, отправки, витрины и вебхуков одно право — оно же открывает и чтение.
* — все права. Доступно только ключам и MCP-подключениям; в роль участника * положить нельзя.

Каталог прав

Документы

documents:read — список и карточка документа, PDF и DOCX, выгрузки Excel/CSV, статистика, список оплат.
documents:write — создание и правка, копии и производные документы, аннулирование, теги, связки счёт↔акт, нумерация, общий доступ, ответы на предложения правок.
documents:delete — удаление документа.
documents:sign — отметка подписи акта и её снятие.
payments:write — отметки «оплачен» / «не оплачен», добавление платежа, сверка банковской выписки (предпросмотр и применение), ссылка на онлайн-оплату.
send:write — отправка документа на email, напоминания об оплате, история отправок.
public_links:write — публичные ссылки: создание, включение, отзыв.

Контрагенты и заказы

counterparties:read — список и карточка контрагента, его банковские счета.
counterparties:write — создание и правка контрагента, его счета.
counterparties:delete — удаление контрагента.
orders:read — список заказов.
orders:write — создание, правка, удаление заказов.

Товары и витрина

products:read — каталог, рубрики, наборы характеристик, настройки витрины (чтение).
products:write — товары и услуги, фото, рубрики, наборы характеристик, массовые операции.
products:delete — удаление товара, в том числе массовое.
storefront:write — создание, настройки, состав и удаление витрины.

Оформление

templates:read — список шаблонов и переменные.
templates:write — создание, правка, удаление шаблонов, шаблон по умолчанию.
assets:write — логотип, печать, подпись, наборы оформления (в том числе чтение).
offers:write — оферты (в том числе чтение).

Организация и интеграции

organizations:read — карточка организации, банковские счета, способы оплаты.
organizations:write — реквизиты, банковские счета, способы оплаты, настройки документов.
webhooks:write — вебхуки: приёмники, журнал доставок, повторы (в том числе чтение). Только владельцу и администраторам.

Готовые наборы для ключей и MCP

Выдавайте ключу ровно то, что нужно сценарию:

Робот по выписке (сверяет оплаты из банка): documents:read, payments:write. Создавать и удалять документы такой ключ не сможет.
Интеграция с CRM (выставляет счета, отправляет клиенту): documents:read, documents:write, counterparties:read, counterparties:write, send:write, public_links:write.
Отчётность и BI (только выгрузка): documents:read, counterparties:read, orders:read.
Ассистент через MCP для ведения документов: те же права, что у интеграции с CRM; отметки оплаты — добавьте payments:write.

POST https://api.apiin.ru/api/organizations/{org_id}/api-keys
{
  "name": "Сверка выписки",
  "kind": "permanent",
  "scopes": ["documents:read", "payments:write"],
  "organization_ids": ["<uuid>"]
}

Без нужного права API отвечает 403 с кодом forbidden; чужая организация — 404 (её существование не раскрывается).

Роли участников кабинета

У организации три уровня: владелец, администратор и участник, плюс сколько угодно собственных ролей. Владелец и администратор имеют все права; администратор дополнительно управляет участниками, ролями, API-ключами, MCP-подключениями и вебхуками, но не может удалить организацию и понизить другого администратора. Участник сам по себе прав не имеет и получает их от роли организации — именованного набора из каталога выше, который администратор создаёт из шаблона (двенадцать готовых: менеджер, руководитель продаж, бухгалтер, бухгалтер на аутсорсе, оплаты и сверка, руководитель, ассистент, юрист, каталог и витрина, оформление, только просмотр, все операции) или собирает вручную.

Карточка организации (organizations:read) открыта любому участнику.
Зависимые чтения. У ролей (в отличие от ключей) запись раздела включает его чтение, а работа с документами — просмотр справочников, без которых страницы кабинета не открываются: documents:read → counterparties:read, orders:read; documents:write → documents:read, products:read, templates:read; payments:write, documents:delete, documents:sign, send:write, public_links:write → documents:read; *:write и *:delete → *:read своего раздела. Набор роли сохраняется уже развёрнутым.
В роль нельзя положить webhooks:write и *; интеграции остаются за администраторами.
Правка роли действует сразу: права читаются на каждом запросе, перелогин не нужен.
Роль, назначенную участникам или ожидающим приглашениям, удалить нельзя (409 role_in_use) — сначала переназначьте.
Участник без роли — штатное состояние: приглашение можно отправить «просто участником», роль назначается и снимается в любой момент. Без роли разделы кабинета закрыты, участник видит экран с просьбой обратиться к владельцу или администратору (их адреса показаны там же).

Управление ролями доступно только по сессии кабинета (не по API-ключу): ключ организации не должен раздавать права её людям.

GET    /api/organizations/{org_id}/roles
POST   /api/organizations/{org_id}/roles
       { "name": "Бухгалтер", "description": "…",
         "permissions": ["documents:read", "payments:write", "documents:sign"] }
PATCH  /api/organizations/{org_id}/roles/{id}      — замена целиком
DELETE /api/organizations/{org_id}/roles/{id}      — 409, пока роль назначена

PATCH  /api/organizations/{org_id}/members/{developer_id}
       { "role": "member", "org_role_id": "<uuid роли>" }   — назначить роль
       { "role": "member" }                             — снять роль
POST   /api/organizations/{org_id}/invites
       { "email": "…", "role": "member", "org_role_id": "<uuid роли>" }
       (без org_role_id — участник без роли)

Список организаций GET /api/organizations для сессии кабинета отдаёт у каждой организации my_role, my_role_name и my_permissions — эффективный набор прав текущего пользователя (["*"] у владельца и администратора).

Совместимость

Права стали строже 16 сентября 2026 года. Ключам и MCP-подключениям, выпущенным раньше, к documents:write автоматически добавлены documents:delete, documents:sign и payments:write, к counterparties:write — counterparties:delete, к products:write — products:delete и storefront:write. Поведение существующих интеграций не изменилось; новые ключи получают ровно то, что выбрано при создании.

Как это выглядит для команды — на странице Команда и роли. Создать роль и пригласить коллег можно в кабинете, раздел «Команда».