API-аудит 2026-08-06 и вход в CLI через браузер

apps/docs/content/api/authorization.mdx

@@ -27,6 +27,21 @@ related:
 
 **Доступ к данным** — те же чаты, треды и сообщения, что видит сам пользователь в интерфейсе Пачки. Никаких дополнительных ограничений или расширений у токена нет, он наследует видимость владельца.
 
+Получить такой доступ можно двумя путями, и это не одно и то же:
+
+| | Токен в интерфейсе | Вход через CLI |
+|---|---|---|
+| Как выдаётся | **Автоматизации** > **API**, руками | `pachca auth login`, подтверждение в браузере |
+| Кто выбирает права | вы, при выпуске | не выбираются: берётся весь каталог, урезанный вашей ролью на момент входа |
+| Срок | бессрочный | час, продлевается автоматически |
+| Значение токена | показывается один раз, копируется | в терминал не выводится |
+| Как прекратить доступ | удалить токен в **Автоматизации** > **API** | `pachca auth logout` — токен гасится на сервере сразу |
+| Когда подходит | унести в автоматизацию или CI, передать коллеге | работа руками и агентом на своей машине |
+
+Разница не только в удобстве. Токен из интерфейса вы держите в руках: он бессрочный, его можно скопировать в чужую систему или передать другому человеку — вместе со своими правами. Токен входа через CLI короткоживущий и привязан к машине, где выполнен вход, поэтому переносить его бессмысленно.
+
+Любой токен, с которым работает CLI, хранится в хранилище ключей операционной системы — и полученный входом через браузер, и переданный через `--token`. Там, где хранилища нет (headless-машина, контейнер), токен ложится в файл конфигурации открытым текстом, и CLI сообщает об этом при входе. Подробнее — в разделе [CLI: авторизация](/guides/cli/authentication#gde-hranitsya-token).
+
 ### Токен бота
 
 Действует от имени бота. Подходит для сервисных интеграций независимо от конкретного пользователя: чат-боты, уведомления из внешних систем, обработка вебхуков, интерактивные формы.
@@ -43,6 +58,7 @@ related:
 
 | Задача | Тип токена | С чего начать |
 | --- | --- | --- |
+| Работа с API руками или агентом на своей машине | Персональный | [CLI: авторизация](/guides/cli/authentication) |
 | Скрипт или утилита от вашего имени, личная автоматизация, разовая выгрузка данных | Персональный | [Создание персонального токена](#sozdanie-personalnogo-tokena) |
 | Чат-бот, уведомления из внешних систем, обработка вебхуков, интерактивные формы | Бот | [Боты](/guides/bots/overview) |
 | Агент или headless-интеграция без участия человека (CI, сервер, облачный воркер) | Бот | [Агенты и headless-интеграции](#agenty-i-headless-integratsii) |

apps/docs/content/guides/audit-events.mdx

@@ -79,6 +79,9 @@ related:
 | `bot_deleted`, `bot_token_recreated` | `bot_id`, `actor_id` |
 | `bot_scopes_updated` | `added_scopes`, `removed_scopes` |
 | `bot_webhook_settings_updated` | `changes` — объект, где ключ это имя настройки, а значение содержит `previous` и `new` |
+| `bot_oauth_client_updated` | `client_id`, `changes` — объект, где ключ это имя параметра клиента, а значение содержит `previous` и `new` |
+| `oauth_authorization_granted` | `client_id`, `scopes` |
+| `oauth_authorization_revoked` | `client_id`, `revoked_tokens_count` |
 | `kms_encrypt`, `kms_decrypt` | `chat_id`, `message_id`, `reason` |
 | `dlp_violation_detected` | `dlp_rule_id`, `dlp_rule_name`, `message_id`, `chat_id`, `user_id`, `action_message`, `conditions_matched` |
 | `search_users_api`, `search_chats_api`, `search_messages_api` | `search_type`, `query_present`, `cursor_present`, `limit`, `filters` |

apps/docs/content/guides/bots/setup.mdx

@@ -56,6 +56,8 @@ related:
   <Step title="Отправьте запрос на создание">
     Передайте параметры бота в объекте `bot.webhook`: имя, никнейм, Webhook URL, список событий и команды. Никнейм должен заканчиваться на `_bot`.
 
+    Обязательное поле одно — имя. Его и никнейм можно передать и на уровне `bot`, тогда объект `bot.webhook` не нужен: `{"bot": {"name": "Бот задач"}}` создаст бота с настройками вебхука по умолчанию.
+
     Тип бота — в один или несколько чатов — задаётся полем `single_chat` и только при создании: изменить его потом нельзя, как и тип бота в интерфейсе. Ограничение «в один чат» распространяется только на беседы и каналы, треды и личные сообщения не в счёт.
   </Step>
   <Step title="Сохраните access_token">

apps/docs/content/guides/cli/authentication.mdx

@@ -9,7 +9,90 @@ related:
 
 # Авторизация
 
-Для работы CLI нужен API-токен Пачки. Получить его можно в интерфейсе: **Настройки** > **Автоматизации** > **API**. Типы токенов (персональный и бота), скоупы и настройка доступа описаны в руководстве [Авторизация](/api/authorization). Ниже — как передать токен в CLI: профили, приоритет источников, headless-режим для CI и агентов.
+Войти в CLI можно двумя способами: через браузер или передав готовый токен. Первый подходит, когда вход выполняет человек, второй — CI и агентам, где подтверждать некому. Типы токенов, скоупы и настройка доступа описаны в руководстве [Авторизация](/api/authorization).
+
+## Вход через браузер
+
+CLI покажет адрес и код подтверждения, откроет браузер и будет ждать. Введите код на открывшейся странице и подтвердите доступ — в терминале появится, под кем вы вошли.
+
+```bash
+pachca auth login
+
+#   Откройте https://app.pachca.com/apps/authorize
+#   и введите код: BCDF-GHJK
+#
+#   Ожидаю подтверждения…
+```
+
+Код нужно ввести руками: ссылку с уже подставленным кодом CLI не печатает, потому что такая ссылка работает как фишинг, если переслать её на чужое устройство. Код заодно кладётся в буфер обмена.
+
+На экране подтверждения показан список запрашиваемых прав — выбирать из него нельзя. CLI запрашивает весь каталог, но выдаётся только то, что доступно вашей роли: набор фиксируется в момент подтверждения и дальше не меняется, даже если роль изменится. Что в итоге выдано, показывает `pachca auth status`.
+
+Токен такого входа живёт **час** и продлевается сам: перед каждой командой CLI проверяет срок и при необходимости обновляет токен. Когда параллельно работает несколько процессов (частый случай у агентов), обновляет только один из них, остальные дожидаются результата.
+
+Флаг `--no-browser` печатает адрес и код, но браузер не открывает — для машин без графической среды.
+
+Под капотом — стандартный вход по коду устройства (OAuth 2.0 Device Authorization Grant, [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)). CLI не открывает локальный порт и не принимает редирект, поэтому одинаково работает на ноутбуке, в SSH-сессии и в контейнере.
+
+## Где хранится токен
+
+Токен уходит в хранилище ключей операционной системы: Keychain на macOS, Secret Service на Linux, Диспетчер учётных данных на Windows. Файл конфигурации хранит только имя, почту и права — секрета в нём нет.
+
+Это касается **обоих способов входа**. Готовый токен, переданный через `--token`, хранится там же, и для него это важнее: он бессрочный, поэтому утёкшее значение не протухнет само.
+
+Так сделано потому, что прав `600` на файле недостаточно: они закрывают доступ другим пользователям машины, но не коду, работающему от вашего имени, а сегодня это обычное дело — postinstall-скрипты, расширения редактора, агенты. Известны кампании, которые прочёсывают домашний каталог в поиске именно таких файлов.
+
+Где лежит токен, показывает `pachca auth status`:
+
+```bash
+pachca auth status
+
+#   Хранение: хранилище ключей ОС
+```
+
+Если хранилища нет — headless-машина, контейнер, минимальный образ, — CLI сохранит токен в файл и скажет об этом прямо при входе. Отказаться от хранилища можно и вручную: флагом `--insecure-storage` при входе или переменной `PACHCA_SECRET_STORE=file` для всех команд.
+
+<Warning>При хранении в файле токен лежит открытым текстом в `~/.config/pachca/config.toml`. Файл читается так же, как любой другой: у всех, кто имеет доступ к вашей учётной записи на машине, есть и доступ к API от вашего имени.</Warning>
+
+Токен привязан к машине, на которой выполнен вход: скопированный на другую машину профиль не заработает — секрет остался в хранилище исходной. Если запись в хранилище пропала или оно заблокировано, `auth status` покажет это, а любая команда попросит войти заново.
+
+## Вход готовым токеном
+
+Получить токен можно в интерфейсе: **Настройки** > **Автоматизации** > **API**.
+
+```bash
+echo "$PACHCA_TOKEN" | pachca auth login --token -
+```
+
+`-` вместо значения читает токен из потока ввода. Так секрет не попадает ни в историю оболочки, ни в список процессов, где его видят другие пользователи машины. Для готового токена это важнее, чем для любого другого: он бессрочный, поэтому утёкшее значение не протухнет само.
+
+Передать значение аргументом тоже можно — короче для разовой настройки, но след останется в обоих местах:
+
+```bash
+pachca auth login --token YOUR_ACCESS_TOKEN
+```
+
+Такой токен не обновляется. Это единственный путь для CI и скриптов: без человека у терминала подтвердить вход в браузере невозможно, поэтому `pachca auth login` без `--token` в неинтерактивном режиме сразу отвечает ошибкой.
+
+## Состояние входа
+
+`pachca auth status` показывает, каким способом выполнен вход, сколько осталось до истечения токена и какие права выданы:
+
+```bash
+pachca auth status
+
+#   Подключён как: Андрей Лукин (andrew@pachca.com)  [user, profile: default]
+#   Вход: через браузер, осталось 52 мин
+#   Права (16): chats:read, messages:read, messages:create, …
+```
+
+Если команда вдруг начала отвечать `403`, начинать разбор стоит отсюда.
+
+Список прав здесь — тот, что был получен при входе, и сам он не обновляется. Разойтись с действительностью он может по разным причинам: у входа через браузер набор определяется ролью и замирает в момент подтверждения, а права готового токена вы могли изменить в настройках токена уже после того, как передали его CLI. Флаг `--remote` спрашивает права у сервера и, если они разошлись, обновляет сохранённые:
+
+```bash
+pachca auth status --remote
+```
 
 ## Профили
 
@@ -36,7 +119,10 @@ pachca auth status
 pachca auth logout bot-notify
 ```
 
-Токены хранятся в `~/.config/pachca/config.toml` с правами `chmod 600`.
+`pachca auth logout` удаляет профиль **с этой машины**. Что при этом происходит с самим токеном, зависит от способа входа:
+
+- **Вход через браузер.** Токен гасится на сервере сразу — доступ закрывается в момент выхода, а не по истечении срока. Если сервер в этот момент недоступен, CLI об этом скажет: профиль всё равно удаляется, а токен доживает свой час. В списке токенов в **Автоматизации** > **API** такая сессия не появляется: она принадлежит приложению «Pachca CLI», а не вам.
+- **Готовый токен.** Продолжит работать — он бессрочный. Удалите его в **Автоматизации** > **API**, если он больше не нужен.
 
 ## Приоритет токена
 
@@ -68,3 +154,35 @@ pachca messages create --profile bot-notify --entity-id 123 --content "Увед
 # CI: токен из секрета, неинтерактивный режим
 PACHCA_TOKEN=$PACHCA_SECRET pachca messages create --entity-id 123 --content "Деплой завершён" --no-input
 ```
+
+## Отказ по правам
+
+Если нужного права нет, команда отвечает `403` и называет само право. API проверяет два условия на каждом вызове: право должно быть у токена **и** его должна давать текущая роль владельца. Отказ означает, что не выполнилось одно из двух, и починка у них разная.
+
+Какое именно — видно в списке прав токена (`pachca auth status`).
+
+**Право в списке есть.** Значит его перестала давать роль — она изменилась после того, как токен был выдан. Помочь может только администратор пространства, повторный вход бесполезен.
+
+```bash
+pachca tasks create --content "Проверить отчёт"
+
+# ✗ Не хватает права tasks:create.
+#   Право у токена есть, но его не даёт текущая роль.
+#   Обратитесь к администратору пространства.
+```
+
+**Права в списке нет.** Дальше зависит от способа входа:
+
+- **Вход через браузер** — набор прав определяется ролью в момент подтверждения и дальше не меняется. Если роль с тех пор расширили, войдите заново: новый токен получит новые права.
+- **Готовый токен** — права выбираются при выпуске, поэтому выпустите токен с нужным набором.
+
+```bash
+pachca tasks create --content "Проверить отчёт"
+
+# ✗ Не хватает права tasks:create.
+#   У токена этого права нет.
+#   Права выдаются по роли в момент входа — если роль с тех пор изменилась,
+#   войдите заново: pachca auth login
+```
+
+В `-o json` то же самое приходит машиночитаемо: тип ошибки `PACHCA_SCOPE_ERROR` и поле `scope` с недостающим правом.