Перейти к содержимому
Для разработчиков

Авторизация

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

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

Типы токенов

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

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

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

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

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

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

Гости и мульти-гости не могут создавать токены любого типа вне зависимости от настроек пространства.

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

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

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

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

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

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

Токен показывается только один раз сразу после создания. Скопируйте и сохраните его в надёжном месте — после закрытия диалога восстановить его будет невозможно.

Токен бота

Бот виден в пространстве как отдельный участник со своим именем и аватаром. Боты создаются в разделе «Автоматизации» → «Интеграции» → «Чат-боты и Вебхуки».

При создании бота нужно выбрать его тип:

  • Для одного чата — подходит для отправки уведомлений из других сервисов. В одном чате можно собрать всех получателей и обсуждать уведомления в тредах
  • Для нескольких чатов — подходит для личного взаимодействия бота с каждым участником компании или разными группами участников
  • Unfurl бот (только для администраторов) — подходит для получения событий об отправке ссылок во всех чатах пространства и создания их предпросмотра

После создания бота его access_token доступен во вкладке «API» настроек бота.

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

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

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

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

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

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

Скоупы

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

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

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

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

Скоупы персональных токенов

При создании персонального токена в интерфейсе Пачки отображаются только те скоупы, которые доступны вашей роли. Например, только Владелец видит все скоупы, включая audit_events:read и chat_exports:read/write. Сотрудник не видит скоупы управления другими пользователями (users:create, users:update, users:delete), их статусами (user_status:read, user_status:write) и тегами (group_tags:write).
string
Скоуп доступа OAuth токена
Возможные значения

Скоупы токенов ботов

Все токены ботов автоматически получают следующий набор разрешений:

  • Сообщения: messages:read, messages:create, messages:update, messages:delete, reactions:read, reactions:write, pins:write, threads:read, threads:create, link_previews:write, views:write
  • Чаты: chats:read, chats:create, chats:update, chats:archive, chats:leave, chat_members:read, chat_members:write
  • Сотрудники: users:read, group_tags:read, custom_properties:read
  • Профиль: profile:read, profile_status:read, profile_status:write
  • Задачи: tasks:read, tasks:create, tasks:update, tasks:delete
  • Файлы: files:read, uploads:write
  • Поиск: search:users, search:chats, search:messages
  • Вебхуки: webhooks:events:read, webhooks:events:delete
Боты не имеют доступа к: audit_events:read, chat_exports:read/write, users:create/update/delete, user_status:read/write, group_tags:write, webhooks:read/write, bots:write.

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

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

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