OАuth авторизация Битрикс24

Создание приложения в Битрикс24

Для создания OAuth приложения необходимо:

Войти в административную панель Битрикс24
Перейти в раздел Разработчикам -> Другое -> Локальные приложения
Нажать кнопку Добавить приложение
Заполнить основные параметры приложения

Обязательные поля при создании приложения:

Название приложения отображается пользователям
Код приложения уникальный идентификатор
Путь для начальной загрузки URL обработчика
Права доступа список разрешений для приложения

Получение учетных данных

После создания приложения система предоставит:

Client ID идентификатор приложения
Client Secret секретный ключ для аутентификации

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

Битрикс24 предоставляет гранулярную систему прав доступа:

crm доступ к CRM функциям
calendar работа с календарем
task управление задачами
user информация о пользователях
telephony интеграция с телефонией
log доступ к ленте новостей
entity работа с пользовательскими сущностями

Процесс OAuth авторизации

Готовый набор запросов для импорта в Postman.

Авторизация

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

https://мой_портал.bitrix24.ru/oauth/authorize/?client_id=код_приложения&response_type=code&redirect_uri=http%3A%2F%2Fexample.ru&scope=права_доступа

Расшифровка параметров:

мой_портал.bitrix24.ru адрес портала
client_id код приложения, который был получен после успешной регистрации приложения
response_type тип ответа всегда сode для authorization code flow
redirect_uri адрес который был указан при создании приложения, необходимо указывать как urlencode, например http%3A%2F%2Fexample.ru
scope запрашиваемые права доступа
state опциональный параметр для защиты от CSRF

Обмен code на access_token

После успешной авторизации пользователь перенаправляется на redirect_uri с параметром сode:

http://redirect_uri/?code=код_получения_авторизации&domain=мой_портал.bitrix24.ru

сode необходимо обменять на access_token, проблема в том, что параметр сode годен в течении 30 секунд, потом протухает. Необходимо создать POST запрос, например в Postman следующего вида:

HeadersContent-Type: application/x-www-form-urlencoded

POSThttps://мой_портал.bitrix24.ru/oauth/token/?grant_type=authorization_code&client_id=код_приложения&client_secret=секретный_ключ&code=полученный_code&redirect_uri=http%3A%2F%2Fexample.ru

Расшифровка параметров:

grant_type всегда authorization_code
client_id код приложения, который был получен после успешной регистрации приложения
client_secret секретный ключ приложения, который был получен после регистрации приложения
сode код получения авторизации который действует 30 секунд
redirect_uri адрес который был указан при создании приложения, необходимо указывать как urlencode, например http%3A%2F%2Fexample.ru
scope требуемый набор разрешений

Структура ответа с токенами:

{
    "access_token": "78032c69007e858c007e53a800000001000007a1cb317d3763a2198a1cf023a59dca5b",
    "expires": 1764492152,
    "expires_in": 3600,
    "scope": "crm",
    "domain": "b24-tx5unf.bitrix24.ru",
    "server_endpoint": "https://oauth.bitrix24.tech/rest/",
    "status": "L",
    "client_endpoint": "https://b24-tx5unf.bitrix24.ru/rest/",
    "member_id": "c8128cfd0e68234bad8cfb58204e9818",
    "user_id": 1,
    "refresh_token": "68825369007e858c007e53a8000000010000078c89879db23f1bb0900272a031ffa291"
}

Работа с access_token

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

Полученный access_token используется для авторизации всех последующих API запросов:

POSThttps://мой_портал.bitrix24.ru/rest/crm.lead.list?auth=ваш_access_token

Альтернативно, токен можно передавать в заголовке Authorization:

HeadersAuthorization: Bearer ваш_access_token

Обновление токена

access_token имеет ограниченное время жизни 1 час. Для получения нового токена используется refresh_token:

HeadersContent-Type: application/x-www-form-urlencoded

POSThttps://ваш-портал.bitrix24.ru/oauth/token/?grant_type=refresh_token&client_id=код_приложения&client_secret=секретный_ключ&refresh_token=ваш_refresh_token