Авторизация

У каждого метода API есть требования для вызова:

• Скоуп токена — почти все методы требуют определённый скоуп. Указан в шапке страницы метода и в OpenAPI-спецификации в поле x-requirements.scope.
• Тарифный план — часть методов доступна только на определённом тарифе (например, экспорт или журнал аудита). Указан в шапке страницы метода рядом со скоупом и в OpenAPI-спецификации в поле x-requirements.plan.
• Права владельца токена — скоуп открывает метод, но не расширяет видимость. Токен работает по тем же правилам, что и интерфейс Пачки: роль в пространстве, роль в чате и участие в нём. Подробнее — в разделе Права и роли.

Типы токенов

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

Персональный токен

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

Доступ к данным — те же чаты, треды и сообщения, что видит сам пользователь в интерфейсе Пачки. Никаких дополнительных ограничений или расширений у токена нет, он наследует видимость владельца.

Получить такой доступ можно двумя путями, и это не одно и то же:

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

Любой токен, с которым работает CLI, хранится в хранилище ключей операционной системы — и полученный входом через браузер, и переданный через --token. Там, где хранилища нет (headless-машина, контейнер), токен ложится в файл конфигурации открытым текстом, и CLI сообщает об этом при входе. Подробнее — в разделе CLI: авторизация.

Токен бота

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

Доступ к данным — все открытые каналы пространства плюс закрытые каналы, беседы и треды, в которые бот добавлен участником. Подробнее о правилах доступа бота к чатам, тредам и личным сообщениям — в разделе Доступы к чатам и сообщениям.

Токен по авторизации

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

Какой токен выбрать

Выберите тип по задаче, которую решает интеграция:

Кто может создавать токены

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

• Кто может создавать интеграции (боты и их токены) — «Только администраторы» или «Администраторы и сотрудники». По умолчанию — «Администраторы и сотрудники».
• Кто может создавать персональные токены — «Только администраторы» или «Все сотрудники». По умолчанию — «Только администраторы»: сотрудники не могут создавать персональные токены, входить в CLI и выдавать доступ ботам на экране согласия. Настройка закрывает только новый доступ: персональные токены, входы в CLI и доступы ботов, выданные до её смены, продолжают работать. Свои персональные токены и входы в CLI сотрудник и после смены настройки видит на странице API и может отозвать, а новые создать не может. Все выданные в пространстве доступы Администратор видит и отзывает на вкладке Все токены.

Настройки доступа к API

Создание персонального токена

Персональные токены создаются на странице Интеграции > API. На ней указан ваш user_id и собраны три списка: персональные токены, токены CLI и авторизации. У Администратора они на вкладке Мои токены, а рядом вкладка с доступами всех сотрудников — подробнее в разделе Все токены пространства.

Страница «API»

Нажмите Создать токен — откроется диалог, в котором нужно задать название токена и выбрать разрешения (скоупы).

Создание API токена

В списке у каждого токена видны дата создания и последнего использования. Меню токена позволяет посмотреть выданные разрешения, изменить название и разрешения или удалить токен. Если токеном пользовались недавно, диалог удаления предупредит об этом: всё, что на нём работает, сломается сразу.

Токены CLI и авторизации

Ниже на той же странице — доступы, которые вы выдали без ручного создания токена:

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

Все токены пространства

У Администратора на странице Интеграции > API две вкладки: Мои токены со списками из раздела выше и Все токены со всеми доступами к API, выданными в пространстве. У остальных сотрудников страница без вкладок.

Вкладка «Все токены»

В таблице по строке на каждый выданный доступ:

• Персональный токен — один токен сотрудника, в колонке Название его имя.
• Токен CLI — один вход в CLI, в названии имя устройства.
• Авторизация бота — бот, которому сотрудник разрешил действовать от своего имени. Строка объединяет все токены этого бота у сотрудника, а имя бота открывает его карточку.

Для каждой строки видно, кому выдан доступ, сколько у него разрешений, когда он выдан и когда им последний раз вызывали API. У входа в CLI вместо числа разрешений стоит «По роли»: набор прав фиксируется при входе и на каждом вызове ограничивается ролью сотрудника. Фильтры по типу, сотруднику и боту и поиск в шапке страницы работают вместе.

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

Окно «Список разрешений»

Отозвать закрывает доступ сразу:

• персональный токен перестаёт работать, восстановить его нельзя;
• вход в CLI на этом устройстве завершается, и сотруднику нужно войти заново, а остальные его входы продолжают работать;
• бот больше не действует от имени сотрудника: все токены, которые сотрудник ему выдал, перестают работать, а у других сотрудников бот работает как раньше.

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

На тарифе Корпорация каждая выдача и каждый отзыв доступа записываются в журнал аудита. Какие события им соответствуют — в разделе Токены и авторизации в журнале.

Получение токена бота

Бот виден в пространстве как отдельный участник со своим именем и аватаром. Получить его access_token можно двумя способами:

• В интерфейсе — на вкладке API в карточке бота: кнопка Создать токен, название и права. Токенов у бота может быть несколько, значение каждого показывается один раз.
• Через API — методом POSTНовый бот: он создаёт бота и сразу возвращает access_token, повторно значение не показывается. Ещё токены выпускает метод POSTНовый токен бота, у каждого своё имя и права.

Несколько токенов у одного бота, их права, перевыпуск и что делать при утечке — в разделе Токены бота.

Методы, требующие токен бота

Некоторые возможности API доступны исключительно с токеном бота:

• DELETEУдаление события истории — удаление события из истории событий бота
• PUTСаморегистрация вебхука бота — бот сам меняет URL своего исходящего вебхука
• POSTUnfurl (разворачивание ссылок) — создание предпросмотров ссылок в сообщениях
• POSTОткрытие представления — открытие модального окна с формой для пользователя

Также только с токеном бота работают поля display_name и display_avatar_url — своё имя и аватар отправителя у отдельного сообщения — в методах POSTНовое сообщение и PUTРедактирование сообщения. С другим токеном запрос с ними вернёт 403. Подробнее — в разделе Подмена имени и аватара отправителя.

Заголовок авторизации

Все запросы к API, кроме метода POSTЗагрузка файла, должны содержать заголовок:

Authorization: Bearer YOUR_ACCESS_TOKEN

Агенты и headless-интеграции

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

Как подключить агента (CLI, llms.txt, Skills) — в разделе AI-агенты. Передача токена в headless-режиме (PACHCA_TOKEN из секретов) — в разделе CLI: авторизация.

Скоупы

Скоупы определяют, к каким методам API имеет доступ токен. Разные типы токенов получают скоупы по-разному:

• Персональный токен — вы выбираете скоупы вручную при создании и можете изменить их позже в настройках токена. Токен получит только запрошенные разрешения.
• Токен бота — права задаются на каждый токен при его создании и редактировании на вкладке API карточки бота. Через API — в методах POSTНовый токен бота и PUTИзменение токена бота, а права основного токена — параметром scopes в методах POSTНовый бот и PUTРедактирование бота. Если скоупы основного токена не указаны, бот получает набор по умолчанию. Какие права можно выдать боту, отдаёт GETКаталог прав бота.

Боту доступны и собственные скоупы самоуправления, недоступные персональным токенам: bot_self:webhook:write — бот сам меняет URL своего исходящего вебхука методом PUTСаморегистрация вебхука бота, и bot_self:write — самостоятельное управление настройками бота.

Бывает и наоборот: bots:read и bots:write для управления ботами, drafts:read и drafts:write для черновиков и отложенных сообщений выдаются только персональным токенам. Скоупы ботов есть у Владельца, Администраторов и Сотрудников, скоупы черновиков — ещё и у мульти-гостя, а токену бота их не получить: с ним метод отвечает 403.

Проверить скоупы текущего токена можно методом GETИнформация о токене.

Доступные скоупы

При создании персонального токена в интерфейсе Пачки отображаются только те скоупы, которые доступны вашей роли. Токену бота права выбираются при создании в его карточке, а через API — параметром scopes при выпуске токена.

Ошибки авторизации

Ошибка авторизации приходит в формате OAuthError с кодом в поле error. Все коды и их значения — в схеме ниже. Методы API отвечают тремя из них:

• 401 Unauthorized с invalid_token
• 403 Forbidden с insufficient_scope
• 403 Forbidden с role_forbidden: новый токен или повторная авторизация этот отказ не исправят

Остальными кодами отвечают методы POSTОбмен кода на токен и POSTОтзыв токена.

Оба ответа 403 дополнительно содержат заголовок WWW-Authenticate по RFC 6750 с тем же кодом в параметре error. У insufficient_scope в параметре scope — скоуп, которого не хватило токену: причину отказа можно разобрать, не разбирая тело ответа.

WWW-Authenticate: Bearer error="insufficient_scope", error_description="Insufficient scope. Required: profile:read", scope="profile:read"

Подробнее о кодах ошибок и структуре ответов — в руководстве Ошибки.