Авторизация
В CLI два способа входа. Они дают разный токен и подходят для разных случаев:
- Вход через браузер —
pachca auth login. Для сотрудника за терминалом: вы подтверждаете вход в Пачке, CLI получает токен на час и сам его продлевает. - Вход готовым токеном —
pachca auth login --tokenили переменнаяPACHCA_TOKEN. Для CI, скриптов и ботов, где подтверждать вход некому: токен создают в Пачке заранее, он бессрочный.
Чем эти два доступа различаются по правам и сроку, показывает таблица в разделе Персональный токен. Какой токен подходит под задачу, подсказывает раздел Какой токен выбрать.
Вход через браузер
Войти через браузер могут администраторы пространства, а остальные сотрудники — если настройка пространства разрешает им персональные токены. Иначе вместо подтверждения откроется отказ «Доступ к API ограничен администраторами пространства»: попросите администратора открыть доступ или войдите готовым токеном бота. Гостям вход недоступен, а мульти-гость входит на тех же условиях, что сотрудник. Подробнее — в разделе Кто может создавать токены.
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 прямо из буфера обмена:
- вместо значения читает токен из потока ввода. Так секрет не попадает ни в историю оболочки, ни в список процессов, где его видят другие пользователи машины. Тем же способом токен передают из менеджера секретов.
Передать значение аргументом тоже можно — короче для разовой настройки, но след останется в обоих местах:
Такой токен не обновляется. Для 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:
Если хранилища нет (headless-машина, контейнер, минимальный образ), CLI сохранит токен в файл и скажет об этом прямо при входе. Отказаться от хранилища можно и вручную: флагом --insecure-storage при входе или переменной PACHCA_SECRET_STORE=file для всех команд.
~/.config/pachca/config.toml, другие варианты пути перечислены в разделе Настройки. Файл читается так же, как любой другой: у всех, кто имеет доступ к вашей учётной записи на машине, есть и доступ к API от вашего имени.Токен привязан к машине, на которой выполнен вход: скопированный на другую машину профиль не заработает — секрет остался в хранилище исходной. Если запись в хранилище пропала или оно заблокировано, auth status покажет это, а любая команда попросит войти заново.
Состояние входа
pachca auth status показывает, чей токен используют команды, каким способом выполнен вход, сколько осталось до истечения токена и какие права выданы:
Если команда вдруг начала отвечать 403, начинать разбор стоит отсюда. auth status берёт токен так же, как остальные команды, в порядке из раздела Приоритет токена. У токена из PACHCA_TOKEN или --token профиля нет, поэтому владельца и права команда спрашивает у сервера. Если переменная PACHCA_TOKEN перекрывает сохранённый профиль, команда называет его:
У сохранённого профиля список прав — копия, сделанная при входе, и сама она не обновляется. С сервером она расходится, когда права готового токена изменили в настройках токена уже после того, как передали его CLI. Флаг --remote спрашивает права токена у сервера и, если они разошлись, обновляет сохранённые:
Ограничения текущей роли в этом списке не видны: роль API проверяет отдельно на каждом вызове, разбор такого отказа — в разделе Отказ по правам.
Профили
CLI поддерживает несколько профилей — удобно, если вы работаете с персональным токеном и токенами ботов одновременно:
У каждого профиля свой вход: один может быть выполнен через браузер, другой готовым токеном.
Выход
pachca auth logout удаляет профиль с этой машины. Что при этом происходит с самим токеном, зависит от способа входа:
- Вход через браузер. CLI отзывает вход на сервере: доступ закрывается в момент выхода, и вход пропадает из списка Токены CLI. Если сохранённый токен уже истёк (так бывает, когда CLI какое-то время не запускали), CLI сначала обновляет его и отзывает уже свежий. В JSON закрытый вход отмечен как
token_revoked: true, в том числе вход, который уже закрыли раньше, например в этом же списке. Если сервер недоступен или ответил ошибкой, CLI скажет, что закрыть вход не удалось, и вернётtoken_revoked: false. Профиль с машины удаляется и в этом случае, а вход остаётся в списке Токены CLI: закройте его там. - Готовый токен. Продолжит работать — он бессрочный. Удалите его на странице Интеграции > API или, если это токен бота, в карточке бота, когда он больше не нужен.
Завершить вход через браузер можно и без терминала: действием Отозвать в списке Токены CLI.
Приоритет токена
При выполнении команды CLI определяет токен в следующем порядке:
- Флаг
--token— разовое использование, без сохранения - Флаг
--profile— конкретный профиль, явно названный в команде, важнее переменнойPACHCA_TOKEN - Переменная
PACHCA_TOKEN— удобно для CI - Переменная
PACHCA_PROFILE— профиль по умолчанию для окружения - Активный профиль — выбранный через
pachca auth switch
CI и агенты (headless)
Если вы в терминале — pachca auth login сохраняет токен в профиль один раз, дальше команды работают без флагов.
Если подключаете агента или настраиваете CI — не сохраняйте токен в файл: передавайте PACHCA_TOKEN через переменную окружения (или --token для разового вызова). Это headless-путь: ничего не пишется на диск, токен берётся из секретов CI/агента. Не коммитьте токен в репозиторий.
Отказ по правам
API проверяет право на каждом вызове дважды: оно должно быть у токена и его должна давать текущая роль владельца токена. Если не выполнилось одно из двух, команда получает 403 и завершается с кодом выхода 3. Какое условие не выполнилось, API сообщает кодом ответа, и починка у них разная.
Права нет у токена — код insufficient_scope. CLI называет недостающее право и подсказывает, что делать:
- Вход через браузер — права определяются ролью в момент подтверждения. Если роль с тех пор расширили, войдите заново тем же профилем: новый токен получит новые права, а прежний вход CLI закроет сам.
- Готовый токен — добавьте право токену в Пачке или выпустите новый токен с нужным набором.
Если в сохранённом списке прав профиля это право есть, CLI скажет, что список устарел: права токена изменили уже после входа. Обновит его pachca auth status --remote.
Право не даёт роль — код role_forbidden. Право у токена есть, но текущая роль владельца это действие не позволяет, например роль понизили уже после выдачи токена. Повторный вход и новый токен не помогут: роль меняет администратор пространства. Токену бота так отвечают методы, которые роль бота не разрешает.
В -o json и в пайпе отказ приходит машиночитаемо. У insufficient_scope тип ошибки PACHCA_SCOPE_ERROR и поле scope с недостающим правом, у role_forbidden — тип PACHCA_AUTH_ERROR и поле message со значением role_forbidden. Все поля ошибок описаны в разделе Ошибки.