Права и роли

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

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

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

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

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

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

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

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

Роль приходит в поле role объекта сотрудника и меняется методом PUTРедактирование сотрудника. Роль guest при редактировании недоступна: назначить её можно только при создании сотрудника методом POSTНовый сотрудник.

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

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

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

Что доступно только Владельцу и Администратору

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

• Только Владелец — chat_exports:read, chat_exports:write для экспорта сообщений и audit_events:read для журнала аудита. Обе возможности доступны на тарифе Корпорация.
• Владелец и Администратор — users:create, users:update, users:delete, user_status:write, user_avatar:write, group_tags:write.
• Только токен бота — bot_self:write и bot_self:webhook:write для самоуправления бота. Персональному токену они недоступны при любой роли.

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

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

Права токена сверяются с текущей ролью владельца при каждом запросе, а не только в момент создания ключа. Поэтому изменения роли отражаются на токене сразу и пересоздавать его не нужно.

Роли в чате

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Гости и мульти-гости видят только те чаты, в которые их добавили. Открытые чаты пространства им недоступны.

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

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

• Состав участников любого чата. 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Список участников чата с параметром role — отдельным запросом на чат.

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

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

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

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

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

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

Если в закрытом чате не осталось активных участников, добавить в него кого-либо через API уже нельзя.

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

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

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

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

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

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

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

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

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

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

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

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