Авторизация

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

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

Типы токенов

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

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

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

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

Токен бота

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

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

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

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

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

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

• Кто может создавать интеграции (токены ботов) — «Только администраторы» или «Администраторы и сотрудники»
• Кто может работать с API (персональные токены) — «Только администраторы» (сотрудники не смогут создавать и использовать персональные токены) или «Все сотрудники»

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

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

Создать персональный токен можно в разделе Автоматизации > API.

На странице отображается список персональных токенов: название, дата создания и дата последнего использования.

Список токенов

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

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

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

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

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

Подробнее о создании и настройке бота — в разделе Боты.

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

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

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

Также при отправке сообщений (POSTНовое сообщение, POSTНовый тред) поля icon_url и name для кастомного аватара и имени отправителя работают только с токеном бота.

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

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

Authorization: Bearer <ACCESS_TOKEN>

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

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

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

Скоупы

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

• Персональный токен — вы выбираете скоупы вручную при создании и можете изменить их позже в настройках токена. Токен получит только запрошенные разрешения.
• Токен бота — скоупы можно выбрать при создании или редактировании бота (параметр scopes в методах POSTНовый бот и PUTРедактирование бота либо во вкладке «API» настроек бота). Если скоупы не указаны, бот получает набор по умолчанию.

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

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

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

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

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

• 401 Unauthorized — токен отсутствует, невалидный или отозван
• 403 Forbidden — токен не имеет необходимого скоупа для данного метода (поле error содержит insufficient_scope)

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