Права и роли

В 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 — создание, настройки, состав и удаление витрины.

Сотрудники

employees:use — выбор сотрудника в доверенности (ФИО и паспорт подставляются), краткий список без паспортов.
employees:read — справочник сотрудников с паспортами (у ролей включает employees:use).
employees:write — добавление, правка, архив и удаление сотрудников (у ролей включает чтение). Ключу, который создаёт сотрудника и передаёт его employee_id в доверенность, нужно ещё employees:use.

Деньги

money:read — раздел «Деньги»: операции, остатки по счетам, расходные документы и чеки, выписки, аналитика.
money:write — ввод операций и чеков, счета и статьи, правила (у ролей включает чтение). Вместе с payments:write — привязка и отвязка платежей к счетам, решения по «?», загрузка и отмена выписки, удаление ручной операции. Снять отметку «Оплачен» со счёта, оплаченного платежом, тоже можно только с money:write.

Сообщения

messages:read — раздел «Сообщения»: переписка с контрагентами, обсуждения документов; в истории взаимодействий контрагента добавляет переписку (саму историю открывают counterparties:read и documents:read).
messages: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, плюс employees:use — выбирать сотрудников в доверенностях (так настроен пресет «Ведение документов» на экране подключения); отметки оплаты — добавьте 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; employees:read → employees:use; money:read → counterparties:read; messages:read → counterparties:read; *:write и *:delete → *:read своего раздела. Набор роли сохраняется уже развёрнутым.
В роль нельзя положить webhooks:write и *; интеграции остаются за администраторами.
Правка роли действует сразу: права читаются на каждом запросе, перелогин не нужен.
MCP-подключение (claude.ai, ChatGPT) — личное: на каждом запросе к правам подключения добавляются членство и роль того, кто его подключил. Участник с ролью не получит через MCP больше, чем даёт роль, а исключённый из команды теряет доступ к организации и через MCP. API-ключи — интеграции организации, от членства не зависят.
Роль, назначенную участникам или ожидающим приглашениям, удалить нельзя (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. Поведение существующих интеграций не изменилось; новые ключи получают ровно то, что выбрано при создании.

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