Упрощенный вариант получения токенов OAuth 2.0

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Приложению, которое открывается во фрейме внутри интерфейса Битрикс24, не нужно проходить полный протокол авторизации. Битрикс24 сам передает готовые токены при каждом открытии приложения.

Токены выдаются на пользователя, который открыл приложение, и ограничены его правами в Битрикс24.

Что приложение получает при открытии

Битрикс24 обращается к адресу приложения POST-запросом: часть параметров приходит в query-строке адреса, остальные — в теле запроса.

Array
(
    [DOMAIN] => portal.bitrix24.ru
    [PROTOCOL] => 1
    [LANG] => ru
    [APP_SID] => dd8cec11e347088fe87c44870a9f1dba
    [AUTH_ID] => ahodg4h37n89vo17gbkgq0x1l825nnb5
    [AUTH_EXPIRES] => 3600
    [REFRESH_ID] => 2lg086mxijlpvwh0h7r4nl19udm4try5
    [SERVER_ENDPOINT] => https://oauth.bitrix24.tech/rest/
    [APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
    [APPLICATION_SCOPE] => crm,entity,im,task
    [member_id] => a223c6b3710f85df22e9377d6c4f7553
    [status] => F
    [PLACEMENT] => DEFAULT
)

Параметры в query-строке адреса приложения

Параметр

Описание

DOMAIN

Адрес Битрикс24, в котором открыто приложение

PROTOCOL

Протокол обращения:

  • 0 — HTTP
  • 1 — HTTPS

LANG

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

APP_SID

Идентификатор сессии приложения. Битрикс24 создает его заново при каждой отрисовке и использует, чтобы связать js-библиотеку с окружением приложения

Параметры в теле POST-запроса

Параметр

Описание

AUTH_ID

Основной авторизационный токен для доступа к REST API. То же, что access_token в полном протоколе

AUTH_EXPIRES

Время жизни AUTH_ID в секундах

REFRESH_ID

Токен продления авторизации. То же, что refresh_token в полном протоколе

SERVER_ENDPOINT

Адрес сервера авторизации, на который приложение обращается за новой парой токенов

APPLICATION_TOKEN

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

APPLICATION_SCOPE

Разделенный запятыми список скоупов, выданных приложению

member_id

Уникальный идентификатор Битрикс24, который не зависит от доменного имени

status

Статус приложения:

  • L — локальное
  • F — бесплатное тиражное
  • S — подписное тиражное

PLACEMENT

Код точки встраивания. У основной страницы приложения — DEFAULT. Для виджетов приходит код точки и дополнительный параметр PLACEMENT_OPTIONS

Примечание

Значение status служит для информации. Чтобы получить доверенный статус, вызовите метод app.info на сервере авторизации: oauth.bitrix24.tech/rest/app.info

Как использовать полученные токены

Со значением AUTH_ID можно сразу вызывать методы REST API — передавайте его в параметре auth.

https://portal.bitrix24.ru/rest/crm.deal.list?auth=ahodg4h37n89vo17gbkgq0x1l825nnb5

Приложение во фрейме может вызывать методы и на стороне браузера — через js-библиотеку методами BX24.callMethod и BX24.callBatch. Авторизацию библиотека подставляет сама.

AUTH_ID живет один час, поэтому для фоновой работы без пользователя сохраните REFRESH_ID — по нему приложение получит новую пару токенов, автоматическое продление токенов OAuth 2.0.

Токены при установке приложения

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

Сохраните в скрипте установки оба токена, в первую очередь REFRESH_ID — тогда приложение сможет работать с REST API и после того, как пользователь закроет фрейм.

Токены для приложения без интерфейса

У приложения, которое работает только через API, страницы во фрейме нет — значит, нет и момента, когда Битрикс24 передаст токены при открытии. Такое приложение получает токены на обработчик, указанный в его настройках: Битрикс24 обращается к обработчику сразу после установки и передает объект auth с обоими токенами. Токены выданы на пользователя, который установил приложение.

Данные приходят в теле POST-запроса в формате application/x-www-form-urlencoded, вложенные объекты — полями с квадратными скобками. Обработчик читает их как обычные поля формы, разбирать JSON не нужно.

$auth = $_POST['auth'] ?? [];
$refreshToken = $auth['refresh_token'] ?? null;

Обработчикам событий refresh_token обычно не приходит. Событие ONAPPINSTALL — исключение: продлить доступ можно только по токену из этого события.

Как настроить обработчик и что в нем сохранить, описано в статьях «Callback установки» — для локального и для тиражного приложения. Состав данных запроса разобран на странице события OnAppInstall.

Важно

Событие может прийти с задержкой, поэтому как единственный источник токенов оно ненадежно. Если токены нужны сразу после установки, продублируйте их получение одним из способов выше.

Что делать дальше

Предыдущая
Полный протокол
Следующая
Автоматическое продление токенов