Автоматическое продление токенов OAuth 2.0

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

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

access_token живет один час. Чтобы не просить пользователя авторизоваться заново, приложение сохраняет у себя refresh_token и обменивает его на новую пару токенов без участия пользователя. Время жизни refresh_token — 180 дней.

Первую пару токенов приложение получает по полному протоколу авторизации OAuth 2.0 или упрощенным способом. Продление работает одинаково для обоих случаев.

В любой момент до истечения срока действия refresh_token приложение может совершить GET-запрос к серверу авторизации:

https://oauth.bitrix24.tech/oauth/token/?
    grant_type=refresh_token
    &client_id=app.573ad8a0346747.09223434
    &client_secret=LJSl0lNB76B5YY6u0YVQ3AW0DrVADcRTwVr4y99PXU1BWQybWK
    &refresh_token=4f9k4jpmg13usmybzuqknt2v9fh0q6rl

Параметры:

Обязательные параметры отмечены *

Параметр

Описание

grant_type*

Тип авторизационных данных. Для продления передайте значение refresh_token

client_id*

Код приложения из партнерского кабинета или из формы локального приложения

client_secret*

Секретный ключ приложения из партнерского кабинета или из формы локального приложения

refresh_token*

Сохраненный токен продления авторизации

Важно

Секретный ключ client_secret участвует только в запросах к серверу авторизации oauth.bitrix24.tech. Не размещайте его в коде, который выполняется в браузере.

Сервер авторизации ответит статусом 200 OK и телом в формате application/json:

{
    "access_token": "ydtj8pho532wydb5ixk78ol7uqlb7sch",
    "client_endpoint": "https://portal.bitrix24.ru/rest/",
    "domain": "oauth.bitrix24.tech",
    "expires": 1780319382,
    "expires_in": 3600,
    "member_id": "a223c6b3710f85df22e9377d6c4f7553",
    "refresh_token": "3s6lr4kr3cv2od4v853gvrchb875bwxb",
    "scope": "crm,entity,im,task",
    "server_endpoint": "https://oauth.bitrix24.tech/rest/",
    "status": "F",
    "user_id": 67
}

Данные ответа:

Параметр

Описание

access_token

Новый основной авторизационный токен для доступа к REST API. Время жизни — один час

refresh_token

Новое значение токена продления. Сохраните его вместо прежнего

expires

Момент истечения срока действия access_token в формате Unix-времени

expires_in

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

client_endpoint

Адрес REST-интерфейса Битрикс24. С него начинаются все вызовы методов

server_endpoint

Адрес REST-интерфейса сервера авторизации

domain

Домен сервера авторизации

member_id

Уникальный идентификатор Битрикс24

scope

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

status

Статус приложения в Битрикс24. Значения совпадают с полем STATUS метода app.info

user_id

Идентификатор пользователя, для которого выдан токен

На этом шаге приложение может получить ошибку. Например, если истек пробный или оплаченный период либо приложение удалили из Битрикс24.

{
    "error": "PAYMENT_REQUIRED",
    "error_description": "Payment required"
}

Другие ошибки сервера авторизации разобраны в статье Коды ошибок.

Когда обновлять сохраненные токены

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

refresh_token действует 180 дней. Если приложение само по себе не обращается к Битрикс24 чаще, достаточно раз в 180 дней запрашивать новую пару токенов, чтобы сохраненная авторизация не истекла.

Не обновляйте токен перед каждым обращением к REST API и не ставьте обновление по расписанию — раз в час или раз в сутки. Такие сценарии создают лишнюю нагрузку на сервер авторизации, и приложение может быть заблокировано автоматикой.

Рекомендуемая логика работы с токенами

  1. Сохраните полученную пару access_token и refresh_token на своей стороне. Держите их в хранилище, недоступном из браузера.
  2. Вызывайте методы REST API с сохраненным access_token.
  3. Дождитесь ошибки expired_token со статусом 401 — она означает, что срок действия токена истек.
  4. Запросите новую пару токенов у сервера авторизации по сохраненному refresh_token.
  5. Сохраните новую пару вместо прежней.
  6. Повторите вызов метода с теми же параметрами и новым access_token.

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

Предыдущая
Упрощенный вариант
Следующая
Коды ошибок