OAuth 2.0 automatic extension

Saving the refresh_token allows the app to use it in the future for getting access REST API without user participation. Refresh_token lifetime - 28 days or until first use.

At any moment before refresh_token expired the app can execute:

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

Parameters (all - required):

grant_type - shows type of authorization data to be validated. Must the value of refresh_token;
client_id - app ID code, received in the partner's account when registering the app or at Bitrix24 account in case of local app;
client_secret - app secret key, received in partner's account when registering the app or at Bitrix24 account in case of local app;
refresh_token - saved authorization token value

Receives JSON as follows:

GET /oauth/token/

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "ydtj8pho532wydb5ixk78ol7uqlb7sch",  
    "client_endpoint": "http://portal.bitrix24.com/rest/",  
    "domain": "oauth.bitrix.info",  
    "expires_in": 3600,  
    "member_id": "a223c6b3710f85df22e9377d6c4f7553",  
    "refresh_token": "3s6lr4kr3cv2od4v853gvrchb875bwxb",  
    "scope": "app",  
    "server_endpoint": "http://oauth.bitrix.info/rest/",  
    "status": "T"
}

Main parameters:

access_token - main auth token, required for accessing REST API (Lifetime - 1 hour.);
refresh_token - new value of additional auth token used for extending saved authorization;
client_endpoint - account REST interface address;
server_endpoint - server REST interface address;
status - app status at the account.

Attention! After the indicated refresh_token query is completed, both such query and jointly issued access_token become invalid! Use new access_token and refresh_token to be able to execute REST API queries and for extending authorization. At the same time, unlimited number of such auth extension chains can exist for a single account user or single app user. However, each of them must be initiated by one of the abovementioned methods for getting authorization, without branching.

Also, at this stage the app can get an authorization error in cases, when, for example, demo or commercial period expires or the app was deleted from the account.

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

When your app scenario requires a continuous data exchange with Bitrix24 without user participation, you need to create a refresh-tokens storage and mechanism for using such tokens. But as was mentioned above, refresh_token saves its validity during 28 days. It means that in cases when your application for some reason does not query Bitrix24 on its own to realze its features, you have to query the auth server once in 28 days to update the saved tokens.

Sometimes, there are cases when app developers, before querying REST, have "contacted" auth server "just in case" to update a token. This scenario is not recommended because it creates an excessive load. The same applies to the scenarios with automatic "token update" once per hour or once per 24 hours: there is no need for such additional extra load.

When you save a couple tokens - access_token and refresh_token - at the app's side, just execute a query to REST by specifying saved access_token (suppose that you, by saving access_token, didn't save data and time of its "expiration"). When token is invalid, you'll receive a corresponding error. In this moment, you need to make a query with saved refresh_token to the auth server for getting a new access_token, and return both new tokens. Save them on the app's side and then execute your REST query with the new access_token.

Bitrix24 Applications