Права и роли

У 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 для журнала аудита, company_chats:read для метода GETСписок чатов пространства и company_bots:read для метода GETСписок ботов пространства. Все они доступны на тарифе Корпорация.
• Владелец и Администратор — users:create, users:update, users:delete, user_status:write, user_avatar:write, group_tags:write для тегов.
• Только токен бота — bot_self:write и bot_self:webhook:write для самоуправления бота. Персональному токену они недоступны при любой роли.
• Только персональный токен — bots:read и bots:write для управления ботами и drafts:read, drafts:write для черновиков и отложенных сообщений — POSTНовый черновик и соседние методы. Роль здесь ни при чём: эти скоупы есть у любого негостевого сотрудника, но токену бота их не выдать, и с ним метод отвечает 403. То есть бот не может ни завести другого бота, ни написать черновик.

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

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

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

Роли в чате

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Перечень чатов всего пространства. 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Добавление пользователей может:

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

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

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

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

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

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

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

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

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

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

GET /api/shared/v1/company/bots

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

Лимит тот же, что у инвентаризации чатов, — около 30 запросов в минуту на токен, он общий на оба метода.

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

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

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

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

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

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

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

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