> Краткое содержание: Как устроены права в API Пачки: роль в пространстве (Владелец, Администратор, Сотрудник, гости) и роль в чате (Создатель, Админ, Редактор, Участник, Подписчик), единственная точка их связи, видимость закрытых бесед и каналов, инвентаризация чатов пространства, управление чужими чатами и чаты уволенных сотрудников
> Это Markdown-версия конкретной страницы. Для контекста за её пределами (правила API, полный перечень методов, авторизация) ОБЯЗАТЕЛЬНО открой [llms.txt](https://dev.pachca.com/llms.txt) перед ответом — это сэкономит токены и предотвратит неполный ответ.


# Права и роли

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

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

[Скоупы](/api/authorization#skoupy) работают поверх этих правил и только сужают доступ. Скоуп открывает методы, но не расширяет видимость: с `chats:read` вы получите те же чаты, что видны в интерфейсе, и ни одним больше.

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

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

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

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

> Различать эти уровни важнее всего при отладке `403`. Прежде чем искать причину в скоупах токена, проверьте, состоит ли выдавший его сотрудник в чате и с какой ролью.


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

Роль приходит в поле `role` объекта сотрудника и меняется методом [Редактирование сотрудника](/api/users/update). Роль `guest` при редактировании недоступна: назначить её можно только при создании сотрудника методом [Новый сотрудник](/api/users/create).

| Роль | Значение `role` | Что даёт |
|---|---|---|
| Владелец | `admin` | Всё, что может Администратор, плюс экспорт сообщений, журнал аудита и состав участников любого чата. В пространстве только один. |
| Администратор | `admin` | Управление сотрудниками и тегами, настройки пространства |
| Сотрудник | `user` | Обычная работа с чатами, сообщениями, тредами и задачами |
| Мульти-гость | `multi_guest` | Доступ только к тем чатам, куда его добавили |
| Гость | `guest` | Доступ к одному чату, в который его пригласили |

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

**Владелец не выделен отдельным значением роли.** В поле `role` у него `admin`, как и у остальных администраторов, и определить Владельца по объекту сотрудника нельзя. Редактировать его чужим токеном нельзя вообще: [Редактирование сотрудника](/api/users/update), [Аватар сотрудника](/api/users/update-avatar) и [Удаление сотрудника](/api/users/delete) возвращают для Владельца `403`. Своим токеном он меняет собственный профиль, но не может сменить себе роль и не может себя деактивировать.

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

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

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

- **Только Владелец** — `chat_exports:read`, `chat_exports:write` для [экспорта сообщений](/guides/export) и `audit_events:read` для [журнала аудита](/guides/audit-events). Обе возможности доступны на тарифе **Корпорация**.
- **Владелец и Администратор** — `users:create`, `users:update`, `users:delete`, `user_status:write`, `user_avatar:write`, `group_tags:write`.
- **Только токен бота** — `bot_self:write` и `bot_self:webhook:write` для самоуправления бота. Персональному токену они недоступны при любой роли.

Полная таблица скоупов по ролям — в разделе [Авторизация](/api/authorization#dostupnye-skoupy).

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

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

| Что произошло с сотрудником | Что с его токеном |
|---|---|
| Роль понизили | Ключ работает, но в объёме новой роли. Скоупы, которые новой роли недоступны, начинают отвечать `403`. |
| Роль вернули | Доступ восстанавливается сам |
| Доступ приостановили | Ключ не работает полностью. Вернули доступ — снова работает. |
| Сотрудника удалили | Ключ не работает и не восстановится |

## Роли в чате

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

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

Роль в чате задаётся методом [Редактирование роли](/api/members/update) и принимает значения `admin`, `editor` и `member`. Роль Создателя изменить нельзя, у него всегда права Админа чата.

> **Внимание:** Роль в чате **не возвращается** в ответе [Списка участников чата](/api/members/list). Поле `role` в объекте сотрудника — это его роль в пространстве, а не в чате. Чтобы получить участников с конкретной ролью в чате, используйте одноимённый параметр запроса `role` со значением `owner`, `admin`, `editor` или `member`.


| Действие | Кто может |
|---|---|
| Читать сообщения и ставить реакции | Все участники чата |
| Создавать треды | Все участники чата |
| Писать сообщения | Создатель, Админ, Редактор, Участник |
| Закреплять сообщения | Создатель, Админ, Редактор, Участник |
| Добавлять участников | Все участники чата, кроме гостей и мульти-гостей |
| Удалять чужие сообщения | Создатель, Админ, Редактор |
| Исключать участников | Создатель, Админ |
| Менять роли участников | Создатель, Админ |
| Менять название и изображение чата | Создатель, Админ |
| Архивировать чат | Создатель, Админ |

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

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

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


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

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

| Кого добавляют | Роль в чате |
|---|---|
| Создателя чата | Создатель |
| Владельца или Администратора пространства | Админ |
| Бота в канал | Редактор |
| Остальных сотрудников | Участник, в канале Подписчик |

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

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

- Сотрудника повысили до Администратора пространства — в чатах, где он уже состоял, он остаётся Участником.
- Администратора понизили до Сотрудника — в своих чатах он остаётся Админом, пока роль не изменят методом [Редактирование роли](/api/members/update).

Поэтому по роли в пространстве нельзя предсказать права в конкретном чате. Проверить, кто в чате Создатель, Админ, Редактор или рядовой участник, можно параметром `role` в [Списке участников чата](/api/members/list).

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

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

- **Открытые беседы и каналы** — видны всем сотрудникам пространства, даже если они не состоят в них.
- **Закрытые беседы и каналы** — видны только участникам. Это правило действует для всех ролей, включая Администратора и Владельца.
- **Личные сообщения** — доступны только собеседникам.
- **Треды** — доступны участникам родительского чата и тем, кого добавили в сам тред. В треде открытого чата — всем сотрудникам пространства. Подробнее — в разделе [Треды](/guides/threads).

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

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

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

- **Состав участников любого чата.** [Список участников чата](/api/members/list) отдаёт участников даже закрытой беседы, где Владелец не состоит. Сообщения через этот метод не раскрываются.
- **Переписка всего пространства.** [Экспорт сообщений](/guides/export) выгружает сообщения из открытых, закрытых и архивных чатов, включая треды, независимо от участия в них. Личные переписки попадают в архив без текста сообщений. Нужен тариф **Корпорация** и скоупы `chat_exports:write` и `chat_exports:read`.

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

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

[Список чатов](/api/chats/list) по умолчанию возвращает только те чаты, где сотрудник состоит участником. Чтобы получить **все открытые беседы и каналы пространства**, независимо от участия в них, передайте параметр `availability` со значением `public`:

```http title="Все открытые чаты пространства"
GET /api/shared/v1/chats?availability=public
```

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

```http title="Открытые чаты пространства вместе с архивными"
GET /api/shared/v1/chats?availability=public&archived=true
```

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

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

Состав участников и администраторов каждого чата возвращает [Список участников чата](/api/members/list) с параметром `role` — отдельным запросом на чат.

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

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

Роль Создателя передать нельзя. [Редактирование роли](/api/members/update) принимает только значения `admin`, `editor` и `member`, а Создателя не меняет: чат навсегда остаётся закреплён за тем, кто его создал.

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

Добавить их в чат методом [Добавление участника в чат](/api/members/add) может:

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

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

> Массовых операций в API нет. Изменение типа доступа, ролей и состава участников выполняется отдельным запросом на каждый чат — учитывайте [лимиты](/api/limits) при обходе большого списка.


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

Чаты **не архивируются автоматически** ни при каких условиях. Архивация происходит только явным вызовом [Архивация чата](/api/chats/archive) или действием в интерфейсе, поэтому уход сотрудника сам по себе к архивации его чатов не приводит.

| Что происходит с чатом | Деактивация сотрудника | Удаление сотрудника |
|---|---|---|
| Участие в беседах и каналах | Сохраняется | Снимается |
| Поле `owner_id` чата | Не меняется | Не меняется |
| Архивация | Не происходит | Не происходит |

После удаления сотрудник перестаёт быть участником своих бесед и каналов, но поле `owner_id` продолжает указывать на него. Управление чатом остаётся у других его Админов, а если Админов не осталось — восстанавливается по схеме из раздела [Управление чатами других сотрудников](#upravlenie-chatami-drugih-sotrudnikov).

Найти чаты, созданные конкретным сотрудником, можно по полю `owner_id` в выдаче [Списка чатов](/api/chats/list), а его текущий статус проверить полем `suspended` в [Информации о сотруднике](/api/users/get).

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

| Что нужно сделать | Метод | Что требуется |
|---|---|---|
| Получить информацию о чате | [Информация о чате](/api/chats/get) | Участие в чате. Для открытых бесед и каналов достаточно быть сотрудником пространства. |
| Получить участников чата | [Список участников чата](/api/members/list) | Участие в чате, либо открытый чат, либо роль Владельца пространства |
| Добавить участника | [Добавление участника в чат](/api/members/add) | Участие в закрытом чате. В открытый чат добавить может любой сотрудник пространства. Гости и мульти-гости добавлять не могут. |
| Изменить роль участника | [Редактирование роли](/api/members/update) | Роль Создателя или Админа в беседе или канале. Нельзя менять роль себе и Создателю, а значение `editor` доступно только в каналах. |
| Исключить участника | [Исключение участника](/api/members/remove) | Роль Создателя или Админа в этом чате. Исключить Создателя нельзя. |
| Отправить сообщение | [Новое сообщение](/api/messages/create) | Право писать в этом чате. Подписчик канала не пишет в самом канале, но может комментировать в его тредах. |
| Создать сотрудника | [Новый сотрудник](/api/users/create) | Роль Администратора или Владельца пространства |
| Экспортировать сообщения | [Создание экспорта](/api/chats/request-export) | Роль Владельца пространства, тариф **Корпорация** |
| Прочитать журнал аудита | [Список событий аудита](/api/security/list) | Роль Владельца пространства, тариф **Корпорация** |

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

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

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

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

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

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

Подробнее о структуре ответов с ошибками — в разделе [Ошибки](/api/errors).


## Связанные разделы

- [Авторизация](/api/authorization)
- [Доступы к чатам и сообщениям](/guides/bots/access)
- [Экспорт сообщений](/guides/export)
- [Треды](/guides/threads)