Kaiten

Документация и инструкции

Log in
Log in
Справочная информацияЧто нового в Кайтене

Дополнения теперь могут делать запросы к Kaiten от имени пользователя

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

Функциональность находится в стадии Beta. Доступна в облачной версии Kaiten.

Что такое дополнение

Дополнение (аддон) — это надстройка, которая расширяет возможности Kaiten. Например, дополнение для GitHub показывает в карточке ветки и пул-реквесты по задаче, а дополнение Google Docs разрешает редактировать документы прямо в Kaiten.

Что изменилось

Раньше аддоны могли расширять интерфейс Kaiten, но не могли выполнять запросы к публичному REST API от имени пользователя. Из-за этого от части сценариев приходилось отказываться.

Теперь аддон может обращаться к API от имени пользователя и выполнять действия, на которые у него есть права в Kaiten.

Это открывает новые сценарии автоматизации. Например, можно:

  • получать данные о карточках и пространствах и создавать или изменять их;

  • собирать данные с разных пространств и строить из них отчет;

  • строить более сложные интеграции с внешними сервисами.

API-клиент для аддонов

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

JavaScript
const api = context.getApiClient()

Разработчику больше не нужно самостоятельно реализовывать получение и обновление доступа к API. Поддерживаются как фронтенд-сценарии (запросы прямо из интерфейса аддона), так и бэкенд-сценарии, когда действия выполняются через сервер аддона.

Метод возвращает API-клиент, через который аддон:

  • проходит авторизацию;

  • получает и обновляет токены доступа;

  • выполняет запросы к публичному REST API.

Авторизация пользователя

  • api.authorize() — запускает OAuth: пользователь видит экран согласия и разрешает аддону доступ. Это происходит один раз — потом повторного согласия не нужно.

    api.authorize() используется только для доступа к публичному REST API Kaiten от имени пользователя. Для авторизации через внешние сервисы, например Google или Яндекс, по-прежнему используется context.authorize(authUrl).

  • api.getAccessToken() — возвращает действующий токен. SDK сам его обновляет, когда срок истекает.

  • api.refreshToken() — если требуется обновить токен принудительно.

Экран согласия с перечнем действий, которые сможет выполнять дополнение

Чтобы использовать возможности API, необходимо создать аддон в портале разработчиков. Для этого пользователю требуется право «Управление дополнениями в портале разработчиков». Владелец компании или администратор выдает это право в разделе Управление компанией → Группы или Управление компанией → Пользователи → Права.

Выполнение запросов к API

Для отправки запросов можно использовать универсальный метод:

await api.request(...)

Или готовые методы:

  • api.get()

  • api.post()

  • api.patch()

  • api.delete()

SDK самостоятельно добавляет авторизацию и обновляет токен при необходимости, поэтому управлять токенами и заголовками вручную не нужно.

Подробное описание параметров, форматов ответов и примеры использования собрали в новом разделе Kaiten API Access портала разработчиков.

Новый раздел Kaiten API Access в документации портала разработчиков

Доступ к API через бэкенд аддона

Бэкенд аддона тоже может получать пользовательские токены и обращаться к API. Для этого используются Addon ID и Addon Secret — их можно найти или сгенерировать в портале «Мои аддоны».

Поле Addon ID в форме редактирования дополнения

Addon ID и секретный ключ

При создании дополнения открывается окно с Addon ID и Addon Secret (секретным ключом). Он используется для настройки доступа к API со стороны сервера аддона.

Окно с Addon ID и секретным ключом после создания дополнения

Что важно знать о секрете:

● При создании аддона секрет показывается один раз. Сразу скопируйте и сохраните его.

● После закрытия окна посмотреть ключ повторно нельзя. Только перегенерировать через меню аддона → Regenerate secret (доступен в меню дополнения в любом статусе).

● После перегенерации старый ключ сразу перестает работать. Обновите его в настройках бэкенда.

● Если бэкенд-доступ не нужен, секрет можно не использовать — окно можно просто закрыть.

Раздел Kaiten API Access в документации портала разработчиков

Полезные ссылки

Didn't find the answer to your question?

Create a request — we'll help you out

Submit a request