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

Авторизация

В CLI два способа входа. Они дают разный токен и подходят для разных случаев:

  • Вход через браузер — pachca auth login. Для сотрудника за терминалом: вы подтверждаете вход в Пачке, CLI получает токен на час и сам его продлевает.
  • Вход готовым токеном — pachca auth login --token или переменная PACHCA_TOKEN. Для CI, скриптов и ботов, где подтверждать вход некому: токен создают в Пачке заранее, он бессрочный.

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

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

Войти через браузер могут администраторы пространства, а остальные сотрудники — если настройка пространства разрешает им персональные токены. Иначе вместо подтверждения откроется отказ «Доступ к API ограничен администраторами пространства»: попросите администратора открыть доступ или войдите готовым токеном бота. Гостям вход недоступен, а мульти-гость входит на тех же условиях, что сотрудник. Подробнее — в разделе Кто может создавать токены.

CLI покажет адрес и код подтверждения, откроет браузер и будет ждать. Введите код на открывшейся странице и подтвердите доступ — в терминале появится, под кем вы вошли. Доступ выдаётся в пространство, открытое в этом браузере: если вы состоите в нескольких, сначала переключитесь на нужное. Если в браузере включено Открывать ссылки в десктоп приложении, страница с кодом откроется в десктопном приложении Пачки, и доступ выдаётся в пространство, открытое в нём.

pachca auth login #   Откройте https://app.pachca.com/apps/authorize#   и введите код: BCDF-GHJK#   (код скопирован в буфер обмена)##   Ожидаю подтверждения…
Запоминать код не нужно: CLI сам копирует его в буфер обмена. Браузер открывается сразу после команды, поэтому на странице подтверждения просто вставьте код.

Ссылку с уже подставленным кодом CLI не печатает: такая ссылка работает как фишинг, если переслать её на чужое устройство.

На экране подтверждения запрашиваемые права собраны в свёрнутые категории. Соглашаются на них целиком, как на экране согласия: выбирать отдельные права нельзя. CLI запрашивает весь каталог, но выдаётся только то, что доступно вашей роли. Набор фиксируется в момент подтверждения и сам не меняется, но каждый вызов проверяется по текущей роли, подробнее в разделе Токен и смена роли. Что в итоге выдано, показывает pachca auth status.

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

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

Код действует 10 минут. Если он истёк или на странице подтверждения нажали Отменить, CLI завершится с кодом выхода 3 и сообщением «Код истёк» или «Вход отклонён в браузере». Запустите pachca auth login снова.

Под капотом — стандартный вход по коду устройства (OAuth 2.0 Device Authorization Grant, RFC 8628). CLI не открывает локальный порт и не принимает редирект, поэтому одинаково работает на ноутбуке, в SSH-сессии и в контейнере.

Каждый такой вход появляется в Пачке отдельной строкой. Подробнее — в разделе Токены CLI в Пачке. Повторный вход тем же профилем заменяет прежний: когда новый вход подтверждён, CLI закрывает прежний на сервере, и тот пропадает из списка. Так же CLI поступает, если в профиль с входом через браузер войти готовым токеном. Если закрыть прежний вход не удалось, например сервер недоступен, CLI предупредит об этом, а новый вход всё равно сохранится. Прежний вход тогда останется в списке и продолжит действовать: отзовите его там. В JSON результат отмечен полем previous_token_revoked.

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

Сначала создайте токен в Пачке: персональный — на странице Интеграции > API, токен бота — на вкладке API в карточке бота. Значение показывается один раз, сразу после создания, поэтому скопируйте его. Токен бота можно и не копировать: CLI выпустит его и сохранит в профиль одной командой, как в разделе Токен бота сразу в профиль.

Скопированный токен передайте CLI прямо из буфера обмена:

# macOSpbpaste | pachca auth login --token - # Linuxxclip -selection clipboard -o | pachca auth login --token - # Windows, PowerShellGet-Clipboard | pachca auth login --token -

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

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

pachca auth login --token YOUR_ACCESS_TOKEN

Такой токен не обновляется. Для CI и скриптов готовый токен — единственный путь: без сотрудника у терминала подтвердить вход в браузере невозможно, поэтому pachca auth login без --token в неинтерактивном режиме сразу отвечает ошибкой. Сохранять токен в профиль там не обязательно: CLI берёт его из переменной окружения PACHCA_TOKEN. Подробнее — в разделе CI и агенты.

Токены CLI в Пачке

Каждый вход через браузер виден в Пачке: на странице Интеграции > API есть список Токены CLI, по строке на вход.

Список «Токены CLI»

В строке показаны начало и конец токена, имя устройства, время входа и время последнего вызова. Имя устройства CLI передаёт сам: это имя машины, а для профиля не по умолчанию к нему добавляется имя профиля в скобках, например macbook-pro (ci). Поэтому два входа с одного ноутбука в списке различаются.

В меню строки два действия:

  • Список разрешений — права, которые получил этот вход
  • Отозвать — завершает вход на выбранном устройстве, остальные входы продолжают работать

После отзыва команды с этим профилем завершаются с кодом выхода 3 и подсказкой войти заново тем же профилем, например pachca auth login --profile ci. Так вход завершают без терминала, например на потерянном ноутбуке.

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

Администратор видит входы всех сотрудников на вкладке Все токены и может завершить любой.

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

Токен уходит в хранилище ключей операционной системы: 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 покажет это, а любая команда попросит войти заново.

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

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

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

Если команда вдруг начала отвечать 403, начинать разбор стоит отсюда. auth status берёт токен так же, как остальные команды, в порядке из раздела Приоритет токена. У токена из PACHCA_TOKEN или --token профиля нет, поэтому владельца и права команда спрашивает у сервера. Если переменная PACHCA_TOKEN перекрывает сохранённый профиль, команда называет его:

PACHCA_TOKEN=YOUR_ACCESS_TOKEN pachca auth status #   Подключён как: Иван Иванов (ivan@example.com)  [user]#   Вход: готовым токеном из PACHCA_TOKEN#   Права по данным сервера (16): chats:read, messages:read, messages:create, …#   Профиль default не используется, пока задан PACHCA_TOKEN. …

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

pachca auth status --remote

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

Профили

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

# Добавить профилиpachca auth login --profile personalpachca auth login --profile bot-notify # Профиль с готовым токеном бота из буфера обмена (macOS)pbpaste | pachca auth login --profile bot-notify --token - # Новый токен бота сразу в профиль, без показа значенияpachca bots create-token <id бота> --name "CLI" --scopes '["profile:read","messages:create"]' \  -o csv -c token --no-header | pachca auth login --profile bot-notify --token - # Список профилейpachca auth list # Переключить активный профильpachca auth switch bot-notify # Статус текущего профиляpachca auth status # Удалить профильpachca auth logout bot-notify

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

Выход

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

  • Вход через браузер. CLI отзывает вход на сервере: доступ закрывается в момент выхода, и вход пропадает из списка Токены CLI. Если сохранённый токен уже истёк (так бывает, когда CLI какое-то время не запускали), CLI сначала обновляет его и отзывает уже свежий. В JSON закрытый вход отмечен как token_revoked: true, в том числе вход, который уже закрыли раньше, например в этом же списке. Если сервер недоступен или ответил ошибкой, CLI скажет, что закрыть вход не удалось, и вернёт token_revoked: false. Профиль с машины удаляется и в этом случае, а вход остаётся в списке Токены CLI: закройте его там.
  • Готовый токен. Продолжит работать — он бессрочный. Удалите его на странице Интеграции > API или, если это токен бота, в карточке бота, когда он больше не нужен.

Завершить вход через браузер можно и без терминала: действием Отозвать в списке Токены CLI.

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

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

  1. Флаг --token — разовое использование, без сохранения
  2. Флаг --profile — конкретный профиль, явно названный в команде, важнее переменной PACHCA_TOKEN
  3. Переменная PACHCA_TOKEN — удобно для CI
  4. Переменная PACHCA_PROFILE — профиль по умолчанию для окружения
  5. Активный профиль — выбранный через 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

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

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

Права нет у токена — код insufficient_scope. CLI называет недостающее право и подсказывает, что делать:

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

Если в сохранённом списке прав профиля это право есть, CLI скажет, что список устарел: права токена изменили уже после входа. Обновит его pachca auth status --remote.

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

pachca users create --email olga@example.com # ✗ Право users:create есть у токена, но его не даёт роль.#   Новый вход или новый токен не помогут: роль меняет администратор пространства.

В -o json и в пайпе отказ приходит машиночитаемо. У insufficient_scope тип ошибки PACHCA_SCOPE_ERROR и поле scope с недостающим правом, у role_forbidden — тип PACHCA_AUTH_ERROR и поле message со значением role_forbidden. Все поля ошибок описаны в разделе Ошибки.