Права и роли

У API почти нет собственной логики доступа. Он работает по тем же правилам, что и интерфейс Пачки: токен видит ровно то, что видит выдавший его сотрудник, и может ровно то же, что может он. Если сотрудник не состоит в закрытом канале, то и его токен не получит оттуда ни сообщений, ни списка участников.

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

Скоупы работают поверх этих правил и только сужают доступ. Скоуп открывает методы, но не расширяет видимость: с chats:read вы получите те же чаты, что видны в интерфейсе, и ни одним больше. Какие скоупы выдать под задачу — в разделе Наборы прав под типовые задачи.

Две системы ролей

Роли в Пачке живут на двух независимых уровнях:

• Роль в пространстве — кем сотрудник является для всей организации.
• Роль в чате — кем он является внутри конкретной беседы или канала.

Уровни не наследуют права друг у друга. Администратор пространства не получает автоматического доступа к чужим чатам: в закрытом канале, где он не состоит, он такой же посторонний, как любой другой сотрудник. И наоборот, обычный сотрудник может быть Создателем канала и управлять там всем, включая администраторов пространства.

Роли в пространстве

Роль приходит в поле role объекта сотрудника и меняется методом PUTРедактирование сотрудника. Роль guest назначают при создании сотрудника методом POSTНовый сотрудник, а сотрудника или мульти-гостя переводят в гости методом редактирования: роль guest передают вместе с chat_ids, где указан один чат. Что при этом происходит — в разделе Перевод в гости.

Две особенности, из-за которых чаще всего возникают вопросы.

Владелец не выделен отдельным значением роли. В поле role у него admin, как и у остальных администраторов, и определить Владельца по объекту сотрудника нельзя. Редактировать его чужим токеном нельзя вообще: PUTРедактирование сотрудника, PUTЗагрузка аватара сотрудника и DELETEУдаление сотрудника возвращают для Владельца 403. Своим токеном он меняет собственный профиль, но не может сменить себе роль и не может себя деактивировать.

Гости не работают с API. Создать токен, войти в CLI или авторизовать бота гость не может: права на работу с API у этой роли нет. Токены, полученные до перевода в гости, при переводе отзываются, и запросы с ними отвечают 401. Ограничение касается только его собственных токенов: сам гость остаётся полноценным участником чата, куда его пригласили, и другие токены видят его как обычного участника.

Мульти-гость работает с API наравне с сотрудником, но видит через него ровно то же, что в интерфейсе. Он создаёт персональные токены, входит в CLI и авторизует ботов, а создавать и настраивать ботов не может. Подробнее — в разделе Мульти-гость в API.

Скоупы, доступные не всем ролям

Большинство скоупов доступно всем ролям, кроме гостя. Исключения стоит знать заранее, потому что при создании токена такие скоупы просто не появятся в списке:

• Только Владелец — chat_exports:read, chat_exports:write для экспорта сообщений, audit_events:read для журнала аудита, company_chats:read для метода GETСписок чатов пространства и company_bots:read для метода GETСписок ботов пространства. Все они доступны на тарифе Корпорация.
• Владелец и Администратор — users:create, users:update, users:delete, user_status:write, user_avatar:write, group_tags:write для тегов.
• Все, кроме мульти-гостя — chats:create, chats:leave, bots:read и bots:write для управления ботами, link_previews:write и скоупы вебхуков webhooks:events:read и webhooks:events:delete. Что из-за этого закрыто мульти-гостю — в разделе Мульти-гость в API.

Отдельно от ролей часть скоупов зависит от типа токена: права самоуправления бота есть только у токена бота, а права управления ботами, черновиков и раздела «Важное» — только у персонального токена. Подробнее — в разделе Скоупы, полная таблица скоупов по ролям — в разделе Доступные скоупы.

Мульти-гость в API

Мульти-гость видит в интерфейсе только чаты, куда его добавили, и их участников. API отдаёт ему ровно столько же:

• Сотрудники — GETСписок сотрудников, GETИнформация о сотруднике и GETСтатус сотрудника отдают его самого, участников общих с ним чатов вместе с ботами и публичных ботов. Треды и архивные чаты общими не считаются, на остальных сотрудников методы отвечают 404. У чужих сотрудников list_tags приходит пустым, а почта и телефон — null.
• Чаты — GETСписок чатов с availability=public отдаёт только открытые чаты, где он участник. Создать беседу или канал он не может, как и выйти из чата: методы POSTНовый чат и DELETEВыход из чата отвечают 403, как и в интерфейсе.
• Напоминания — GETСписок напоминаний с chat_ids отдаёт напоминания только тех чатов, где он участник, и доступных ему тредов: открытые чаты, куда он не вступал, не учитываются.
• Теги — GETСписок тегов и GETИнформация о теге отдают только теги активных бесед и каналов, где он участник. GETСписок сотрудников тега ему закрыт и отвечает 403.
• Упоминания — <@id> в методах POSTНовое сообщение и PUTРедактирование сообщения превращается в упоминание только для доступных ему сотрудников, остальные остаются в тексте как есть.
• Черновики — черновики и отложенные сообщения доступны ему, как сотруднику: скоупы drafts:read и drafts:write выдаются и мульти-гостю. С какими токенами работают черновики — в разделе Работает только личным токеном.
• Боты — скоупы bots:read и bots:write ему не выдаются, поэтому создавать и настраивать ботов он не может. Авторизовать бота и подключить его из витрины — может. Добавлять ботов в чаты он не может ни при какой настройке бота.

Перевод в гости

Сотрудника или мульти-гостя переводят в гости методом PUTРедактирование сотрудника с role: "guest" и chat_ids, где указан чат, в котором он останется. Это должна быть одна активная беседа или канал пространства, куда у токена есть право добавлять участников. Иначе метод отвечает 400 по полю chat_ids и не меняет ничего. Владельца пространства перевести в гости нельзя: метод отвечает 403.

Перевод меняет сразу многое:

• С сотрудника снимаются все теги.
• Он выходит из остальных бесед и каналов, в том числе архивных. Личные переписки и треды остаются.
• В указанный чат его добавляют, если он в нём не состоял. Права Админа или Редактора в этом чате снимаются.
• Все его токены отзываются и отвечают 401: персональные, входы в CLI и доступы, выданные ботам и программам с MCP.

Обратно это не возвращается: если потом повысить роль, чаты, теги и токены не восстановятся. На тарифе Корпорация перевод виден в журнале аудита: смена роли, выход из чатов, снятие тегов и отзыв каждого токена.

Токен и смена роли

Права токена сверяются с текущей ролью владельца при каждом запросе. Набор прав, сохранённый в токене, при этом не меняется: роль ограничивает его на каждом вызове. Поэтому изменения роли отражаются на токене сразу и пересоздавать его не нужно. Так работают все персональные токены, в том числе входы в CLI и токены, выданные ботам и программам с MCP. Исключение — перевод в гости: он отзывает все токены сотрудника.

Токены сотрудника с приостановленным доступом не удаляются: Администратор видит их на вкладке Все токены. Если доступ сотруднику вернут, они снова заработают, поэтому их стоит отозвать заранее.

Роли в чате

Набор ролей зависит от типа чата:

• Беседа — Создатель, Админ, Участник.
• Канал — Создатель, Админ, Редактор, Подписчик.

Роль в чате задаётся методом PUTРедактирование роли участника и принимает значения admin, editor и member. Роль Создателя изменить нельзя, у него всегда права Админа чата.

Подписчик канала читает сообщения и ставит реакции, но не пишет в самом канале. Комментировать в тредах канала он при этом может. Обе роли, Участник и Подписчик, задаются одним значением member: как называется роль, зависит от типа чата.

В треде права определяет роль в чате, где находится родительское сообщение, а в самостоятельном треде — роль в самом треде, где его создатель становится владельцем. Подробнее — в разделе Права в треде.

В открытой беседе или канале любой сотрудник пространства может читать сообщения, ставить реакции и добавлять участников, не вступая в чат. Остальные действия из таблицы требуют участия.

Участника, который попал в чат по тегу, исключение из чата не выводит: его участие задаёт тег. Чтобы такой сотрудник вышел, снимают тег с него или отвязывают тег от чата.

Как роль в пространстве влияет на роль в чате

Связь между двумя системами ровно одна: роль в чате назначается в момент добавления участника, и в этот момент учитывается его роль в пространстве.

В личных сообщениях у обоих собеседников права Админа.

Дальше эта роль живёт самостоятельно и не пересчитывается при смене роли в пространстве. Отсюда два следствия, которые заметны через API:

• Сотрудника повысили до Администратора пространства — в чатах, где он уже состоял, он остаётся Участником.
• Администратора понизили до Сотрудника — в своих чатах он остаётся Админом, пока роль не изменят методом PUTРедактирование роли участника.

Поэтому по роли в пространстве нельзя предсказать права в конкретном чате. Проверить, кто в чате Создатель, Админ, Редактор или рядовой участник, можно параметром role в методе GETСписок участников чата.

Видимость чатов

Видимость определяется участием, а не ролью в пространстве:

• Открытые беседы и каналы — видны всем сотрудникам пространства, даже если они не состоят в них.
• Закрытые беседы и каналы — видны только участникам. Это правило действует для всех ролей, включая Администратора и Владельца.
• Личные сообщения — доступны только собеседникам.
• Треды — видны тем, кому виден родительский чат, и тем, кого добавили в сам тред. Подробнее — в разделе Кто видит тред.

Гости и мульти-гости видят только те чаты, в которые их добавили. Открытые чаты пространства им недоступны. Как это правило действует в API для мульти-гостя — в разделе Мульти-гость в API.

Что доступно Владельцу пространства сверх остальных

Владелец обходит правило участия в трёх местах, и все три доступны только ему. Администратор пространства не получает ничего из этого.

• Перечень чатов всего пространства. GETСписок чатов пространства отдаёт беседы и каналы, включая закрытые, где Владелец не состоит. Личные переписки и треды в выдачу не попадают. Нужен тариф Корпорация и скоуп company_chats:read.
• Состав участников любого чата. GETСписок участников чата отдаёт участников даже закрытой беседы, где Владелец не состоит. Сообщения через этот метод не раскрываются.
• Переписка всего пространства. Экспорт сообщений выгружает сообщения из открытых, закрытых и архивных чатов, включая треды, независимо от участия в них. Личные переписки по умолчанию попадают в архив без текста сообщений, подробнее в разделе Что попадает в архив. Нужен тариф Корпорация и скоупы chat_exports:write и chat_exports:read.

То есть запрет на чтение закрытых чатов ограничивает обычную работу с API, но не перечень и не экспорт: на тарифе Корпорация Владелец видит закрытые чаты в списке и может получить их содержимое в виде архива.

Четвёртая привилегия Владельца лежит за пределами чатов — это полный перечень ботов пространства, включая чужих. Она описана в разделе Инвентаризация ботов пространства.

Инвентаризация чатов пространства

GETСписок чатов по умолчанию возвращает только те чаты, где сотрудник состоит участником. Чтобы получить все открытые беседы и каналы пространства, независимо от участия в них, передайте параметр availability со значением public:

GET /api/shared/v1/chats?availability=public

Архивные чаты по умолчанию не возвращаются ни при одном значении availability. Чтобы получить их вместе с активными, передайте archived=true:

GET /api/shared/v1/chats?availability=public&archived=true

Отличить архивный чат в выдаче можно по полю archived объекта чата — оно приходит всегда, независимо от параметров запроса.

Граница у такой выгрузки одна: закрытые беседы и каналы, где токен не участник, в списке не возвращаются. Для Владельца пространства эту границу снимает отдельный метод — GETСписок чатов пространства:

GET /api/shared/v1/company/chats

Он отдаёт беседы и каналы всего пространства независимо от участия, сразу и активные, и архивные. Оставить одно состояние можно параметром activity со значением active или archived. Личные переписки и треды метод не возвращает. Нужен тариф Корпорация, скоуп company_chats:read и роль Владельца — Администратору метод отвечает 403. Каждый запрос попадает в журнал аудита как событие company_chats_accessed.

Состав участников и администраторов каждого чата возвращает GETСписок участников чата с параметром role — отдельным запросом на чат.

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

Управление чатами других сотрудников

Роль Создателя передать нельзя. PUTРедактирование роли участника принимает только значения admin, editor и member, а Создателя не меняет: чат навсегда остаётся закреплён за тем, кто его создал.

Получить права управления чужим чатом можно другим путём — через автоматическое назначение роли при входе. Владелец или Администратор пространства, попав в чат, сразу становится его Админом и получает управление настройками, участниками, ролями и архивацией.

Добавить их в чат методом POSTДобавление участников может:

• в открытый чат — любой сотрудник пространства, даже не состоящий в нём;
• в закрытый чат — любой его участник, кроме гостей и мульти-гостей.

Если в закрытом чате не осталось активных участников, методом POSTДобавление участников в него уже никого не добавить. Остаётся путь через тег: если к чату привязан тег, сотрудник, которому выдали этот тег, сам попадает в чат. Выдать тег в поле list_tags может Владелец или Администратор пространства, в том числе себе.

Чаты деактивированных и удалённых сотрудников

Чаты не архивируются автоматически ни при каких условиях. Архивация происходит только явным вызовом PUTАрхивация чата или действием в интерфейсе, поэтому уход сотрудника сам по себе к архивации его чатов не приводит.

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

Найти чаты, созданные конкретным сотрудником, можно по полю owner_id в выдаче метода GETСписок чатов, а его текущий статус проверить полем suspended в методе GETИнформация о сотруднике.

Видимость ботов

Видимость бота определяется правом на его редактирование, а не участием в чатах. GETСписок ботов возвращает только тех ботов, которых вам разрешено редактировать: созданных вами и тех, чьи настройки открывают вам доступ. Это правило действует для всех ролей, включая Администратора пространства.

Имя бота, его токены, авторизация от имени сотрудника, страница в витрине и удаление бота доступны только создателю и Администраторам, если настройки бота открывают им доступ. Руководителю чата с ботом эти методы отвечают 403, даже когда остальные настройки ему открыты. Что из этого доступно вам, показывает поле permissions в объекте бота.

Инвентаризация ботов пространства

Полный перечень ботов пространства отдаёт GETСписок ботов пространства:

GET /api/shared/v1/company/bots

Нужен тариф Корпорация, скоуп company_bots:read и роль Владельца — Администратору метод отвечает 403. У ботов, недоступных вам для редактирования, приходят только имя и никнейм, а остальные настройки вебхука и oauth_client — null: адрес исходящего вебхука, события, команды, скоупы и права на редактирование не раскрываются. Форма объекта при этом та же, что у доступных ботов. Каждый запрос попадает в журнал аудита как событие company_bots_accessed.

Лимит у него общий с инвентаризацией чатов.

Наборы прав под типовые задачи

Права выбирают при выпуске токена: токену бота — на вкладке API в карточке бота, персональному токену — на странице Интеграции > API. В окне выбора право находится поиском по коду, например messages:create. Ниже — наборы для частых задач. Права открывают методы, но не расширяют видимость: бот работает только в доступных ему чатах, а персональный токен — в чатах своего сотрудника.

Что дают права из наборов:

• messages:create — отправить сообщение, в том числе с кнопками или в тред
• threads:create — открыть тред у сообщения, чтобы ответить в нём
• reactions:write — поставить реакцию, например отметить, что запрос принят
• messages:read, chats:read, chat_members:read, threads:read — прочитать сообщения, сведения о чате, его участников и треды
• profile:read — узнать свой id методом GETСвой профиль, по нему же Pachca Trigger отличает токен бота от персонального
• messages:update — изменить своё сообщение, например заменить кнопки после нажатия
• views:write — открыть форму и ответить на её отправку, только с токеном бота
• users:read, search:users, search:chats и search:messages — найти сотрудника, чат или сообщение
• files:read — скачать вложение, uploads:write — отправить файл
• bot_self:webhook:write — Pachca Trigger сам прописывает боту адрес вебхука, при ручной настройке адреса право не нужно

Что добавить к набору по задаче:

Входу в CLI и программе, подключённой к MCP через браузер, права вручную не выбирают, подробнее в разделе Скоупы. Если методу не хватает права, он отвечает 403 с кодом insufficient_scope, а недостающий скоуп назван в заголовке WWW-Authenticate и в шапке страницы метода. Добавьте право в меню токена: новые права действуют сразу. Права для отдельных операций n8n — в разделе Недостаточно прав (403 Forbidden).

Требования частых методов

Личные данные сотрудников

Поля email и phone_number в объекте сотрудника выдаются не всем:

• Владелец и Администратор видят их всегда.
• Сотрудник видит их, если в настройках пространства разрешён показ личных данных. Иначе оба поля приходят как null, кроме собственного профиля.
• Токен бота подчиняется только этой настройке пространства и привилегию Администратора не наследует ни при каких условиях.

Собственные email и phone_number доступны всегда, независимо от роли и настройки.

Ошибки доступа

• 403 Forbidden — прав недостаточно. Причин пять: нужного скоупа нет в токене (поле error содержит insufficient_scope, недостающий скоуп дублируется в заголовке WWW-Authenticate), скоуп в токене есть, но недоступен текущей роли владельца (role_forbidden), у выдавшего токен сотрудника нет права на действие (он не состоит в чате или его роль в чате ниже требуемой), возможность не входит в тариф пространства (методы с пометкой Корпорация), либо доступ выдавшего токен сотрудника приостановлен или сотрудник удалён (код access_denied, подробнее в разделе Токен и смена роли).
• 404 Not Found — объекта не существует. Чат, сообщение, тред, файл или экспорт другого пространства отвечают так же. Если чат вашего пространства существует, но недоступен, вернётся 403.
• 402 Payment Required — работа пространства приостановлена: израсходован лимит сообщений тарифа, а на платном тарифе к этому добавляется неоплата. Приходит с кодом payment_required вместо ожидаемого ответа. Приостановка задевает не все методы: профиль и статусы, реакции, закрепления, превью ссылок, создание треда под сообщением, состав и архивация чатов, экспорт продолжают работать. Поэтому 402 объявлен не у каждого метода — смотрите список ответов на странице нужного.

Подробнее о структуре ответов с ошибками — в разделе Ошибки.