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

Сохраняя на своей стороне значение токена продления авторизации refresh_token, приложение может в дальнейшем использовать его для получения доступа к REST API уже без участия пользователя. Время жизни refresh_token составляет 180 дней.

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

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

Параметры:

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

• grant_type* — параметр, показывающий тип авторизационных данных, подлежащих валидации. Должен иметь значение refresh_token;
• client_id* — код приложения, получаемый в партнерском кабинете при регистрации приложения, либо на портале в случае локального приложения;
• client_secret* — секретный ключ приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
• refresh_token* — значение сохраненного токена продления авторизации.

В ответ приложение получит json следующего вида:

GET /oauth/token/
        
        HTTP/1.1 200 OK
        Content-Type: application/json
        
        {
            "access_token": "ydtj8pho532wydb5ixk78ol7uqlb7sch",
            "client_endpoint": "http://portal.bitrix24.com/rest/",
            "domain": "oauth.bitrix24.tech",
            "expires_in": 3600,
            "member_id": "a223c6b3710f85df22e9377d6c4f7553",
            "refresh_token": "3s6lr4kr3cv2od4v853gvrchb875bwxb",
            "scope": "app",
            "server_endpoint": "http://oauth.bitrix24.tech/rest/",
            "status": "T"
        }
        

Значимые данные ответа:

• access_token — основной авторизационный токен, требуемый для доступа к REST API (время жизни — 1 час)
• refresh_token — новое значение дополнительного авторизационного токена, служащего для продления сохраненной авторизации
• client_endpoint — адрес REST-интерфейса портала
• server_endpoint — адрес REST-интерфейса сервера
• status — статус приложения на портале

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

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

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

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

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

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

• Сохраняйте полученные пары access_token и refresh_token токенов на своей стороне;
• Используйте сохраненные access_token для выполнения запросов;
• Если конкретный access_token потерял актуальность, вы получите в ответ соответтствующую ошибку. В этот момент надо:
  • Сделать запрос к серверу авторизации на получение новой пары токенов, используя сохраненный refresh_token;
  • Сохранить новую пару токенов на своей стороне;
  • Повторить запрос к методу REST с теми же параметрами, что и раньше, но с новым access_token.