Для разработчиков

Авторизация

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

Вход через браузер

CLI покажет адрес и код подтверждения, откроет браузер и будет ждать. Введите код на открывшейся странице и подтвердите доступ — в терминале появится, под кем вы вошли.

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). CLI не открывает локальный порт и не принимает редирект, поэтому одинаково работает на ноутбуке, в SSH-сессии и в контейнере.

Где хранится токен

Токен уходит в хранилище ключей операционной системы: Keychain на macOS, Secret Service на Linux, Диспетчер учётных данных на Windows. Файл конфигурации хранит только имя, почту и права — секрета в нём нет.

Это касается обоих способов входа. Готовый токен, переданный через --token, хранится там же, и для него это важнее: он бессрочный, поэтому утёкшее значение не протухнет само.

Так сделано потому, что прав 600 на файле недостаточно: они закрывают доступ другим пользователям машины, но не коду, работающему от вашего имени, а сегодня это обычное дело — postinstall-скрипты, расширения редактора, агенты. Известны кампании, которые прочёсывают домашний каталог в поиске именно таких файлов.

Где лежит токен, показывает pachca auth status:

pachca auth status #   Хранение: хранилище ключей ОС

Если хранилища нет — headless-машина, контейнер, минимальный образ, — CLI сохранит токен в файл и скажет об этом прямо при входе. Отказаться от хранилища можно и вручную: флагом --insecure-storage при входе или переменной PACHCA_SECRET_STORE=file для всех команд.

При хранении в файле токен лежит открытым текстом в ~/.config/pachca/config.toml. Файл читается так же, как любой другой: у всех, кто имеет доступ к вашей учётной записи на машине, есть и доступ к API от вашего имени.

Токен привязан к машине, на которой выполнен вход: скопированный на другую машину профиль не заработает — секрет остался в хранилище исходной. Если запись в хранилище пропала или оно заблокировано, auth status покажет это, а любая команда попросит войти заново.

Вход готовым токеном

Получить токен можно в интерфейсе: Настройки > Автоматизации > API.

echo "$PACHCA_TOKEN" | pachca auth login --token -

- вместо значения читает токен из потока ввода. Так секрет не попадает ни в историю оболочки, ни в список процессов, где его видят другие пользователи машины. Для готового токена это важнее, чем для любого другого: он бессрочный, поэтому утёкшее значение не протухнет само.

Передать значение аргументом тоже можно — короче для разовой настройки, но след останется в обоих местах:

pachca auth login --token YOUR_ACCESS_TOKEN

Такой токен не обновляется. Это единственный путь для CI и скриптов: без человека у терминала подтвердить вход в браузере невозможно, поэтому pachca auth login без --token в неинтерактивном режиме сразу отвечает ошибкой.

Состояние входа

pachca auth status показывает, каким способом выполнен вход, сколько осталось до истечения токена и какие права выданы:

pachca auth status #   Подключён как: Андрей Лукин (andrew@pachca.com)  [user, profile: default]#   Вход: через браузер, осталось 52 мин#   Права (16): chats:read, messages:read, messages:create, …

Если команда вдруг начала отвечать 403, начинать разбор стоит отсюда.

Список прав здесь — тот, что был получен при входе, и сам он не обновляется. Разойтись с действительностью он может по разным причинам: у входа через браузер набор определяется ролью и замирает в момент подтверждения, а права готового токена вы могли изменить в настройках токена уже после того, как передали его CLI. Флаг --remote спрашивает права у сервера и, если они разошлись, обновляет сохранённые:

pachca auth status --remote

Профили

CLI поддерживает несколько профилей — удобно, если вы работаете с персональным токеном и токенами ботов одновременно:

# Добавить профилиpachca auth login --profile personalpachca auth login --profile bot-notify # Для CI — передайте токен через флагpachca auth login --profile bot-notify --token YOUR_ACCESS_TOKEN # Список профилейpachca auth list # Переключить активный профильpachca auth switch bot-notify # Статус текущего профиляpachca auth status # Удалить профильpachca auth logout bot-notify

pachca auth logout удаляет профиль с этой машины. Что при этом происходит с самим токеном, зависит от способа входа:

  • Вход через браузер. Токен гасится на сервере сразу — доступ закрывается в момент выхода, а не по истечении срока. Если сервер в этот момент недоступен, CLI об этом скажет: профиль всё равно удаляется, а токен доживает свой час. В списке токенов в Автоматизации > API такая сессия не появляется: она принадлежит приложению «Pachca CLI», а не вам.
  • Готовый токен. Продолжит работать — он бессрочный. Удалите его в Автоматизации > API, если он больше не нужен.

Приоритет токена

При выполнении команды CLI определяет токен в следующем порядке:

  1. Флаг --token — разовое использование, без сохранения
  2. Переменная PACHCA_TOKEN — удобно для CI
  3. Флаг --profile или переменная PACHCA_PROFILE — конкретный профиль
  4. Активный профиль — выбранный через pachca auth switch
# Токен через флаг (разово, без сохранения)pachca users list --token YOUR_ACCESS_TOKEN # Токен через переменную окружения (CI)PACHCA_TOKEN=YOUR_ACCESS_TOKEN pachca users list # Конкретный профиль для одной командыpachca messages create --profile bot-notify --entity-id 123 --content "Уведомление"

CI и агенты (headless)

Если вы в терминале — pachca auth login сохраняет токен в профиль один раз, дальше команды работают без флагов.

Если подключаете агента или настраиваете CI — не сохраняйте токен в файл: передавайте PACHCA_TOKEN через переменную окружения (или --token для разового вызова). Это headless-путь: ничего не пишется на диск, токен берётся из секретов CI/агента. Не коммитьте токен в репозиторий.

# CI: токен из секрета, неинтерактивный режимPACHCA_TOKEN=$PACHCA_SECRET pachca messages create --entity-id 123 --content "Деплой завершён" --no-input

Отказ по правам

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

Какое именно — видно в списке прав токена (pachca auth status).

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

pachca tasks create --content "Проверить отчёт" # ✗ Не хватает права tasks:create.#   Право у токена есть, но его не даёт текущая роль.#   Обратитесь к администратору пространства.

Права в списке нет. Дальше зависит от способа входа:

  • Вход через браузер — набор прав определяется ролью в момент подтверждения и дальше не меняется. Если роль с тех пор расширили, войдите заново: новый токен получит новые права.
  • Готовый токен — права выбираются при выпуске, поэтому выпустите токен с нужным набором.
pachca tasks create --content "Проверить отчёт" # ✗ Не хватает права tasks:create.#   У токена этого права нет.#   Права выдаются по роли в момент входа — если роль с тех пор изменилась,#   войдите заново: pachca auth login

В -o json то же самое приходит машиночитаемо: тип ошибки PACHCA_SCOPE_ERROR и поле scope с недостающим правом.