Авторизация

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

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

Типы токенов

В Пачке есть два типа токенов:

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

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

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

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

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

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

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

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

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

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

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

Токен бота

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

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

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

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

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

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

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

Authorization: Bearer <ACCESS_TOKEN>

Скоупы

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

• Персональный токен — вы выбираете скоупы вручную при создании и можете изменить их позже в настройках токена. Токен получит только запрошенные разрешения.
• Токен бота — скоупы задаются автоматически и не настраиваются. Все боты (входящие вебхуки, исходящие вебхуки, unfurl-боты) получают одинаковый фиксированный набор разрешений.

При добавлении новых скоупов в API токены ботов обновляются автоматически, а в персональных токенах новые скоупы можно включить в настройках токена.

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

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

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

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

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

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