Forcefully Refresh Authorization Data BX24.refreshAuth
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
BX24.refreshAuth([someCallback: function]): void;
The BX24.refreshAuth function forcefully refreshes the OAuth 2.0 authorization data: Bitrix24 issues the application a new pair of access_token and refresh_token. The refreshed data is passed to the someCallback handler function.
The function works only after BX24.init and only inside an application frame. It does not require a scope of its own.
When to Call the Function
Requests to Bitrix24 do not need a forced refresh: before a BX24.callMethod call, the library checks the token expiration by itself, and when a response returns the expired_token error, it refreshes the token and repeats the request.
Call refreshAuth only if your code needs a fresh token sooner — for example, to pass it to your own server. An access_token is valid for one hour. A server that works with Bitrix24 continuously needs both tokens: retain them and replace the previous values with the new ones.
From that point on, the server renews the authorization by itself, without the application frame — with a request to the authorization server. This scenario is described in OAuth 2.0 Token Automatic Renewal. The same article explains why authorization should not be renewed on a schedule.
Function Parameters
|
Name |
Description |
|
someCallback |
A handler that runs after the tokens are refreshed. It receives an object with authorization data — the same one that BX24.getAuth returns. Without a handler the tokens are refreshed as well, but the application does not receive them |
Code Example
How to Use Examples in Documentation
BX24.init(() => {
const button = document.createElement('button');
button.textContent = 'Refresh auth';
button.addEventListener('click', () => {
BX24.refreshAuth((refreshedAuthInfo) => {
// pass the fresh tokens to your own server so that it works with Bitrix24 on behalf of the application.
// tokens are secret: do not log them and do not retain them in the browser
fetch('https://example.com/b24/tokens', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
memberId: refreshedAuthInfo.member_id,
accessToken: refreshedAuthInfo.access_token,
refreshToken: refreshedAuthInfo.refresh_token
})
})
.then((response) => console.log('B24: tokens sent, status: ', response.status))
.catch((error) => console.error('B24: tokens are not sent: ', error));
})
});
document.body.appendChild(button);
});
Response Handling
The function returns no data (void). The result is passed to someCallback: the tokens and their expiration time in it are new, while domain and member_id stay the same.
{
"access_token": "7f2ab466006efd82005fdecc00000000a1c4de93bb6d11e0a3c25f7b91d4c2a8",
"refresh_token": "b03fd266006efd82005fdecc0000000041e7c85d0f2a44b8a6d1e3c7594fb102",
"expires_in": 1720015327002,
"domain": "mycompany.bitrix24.com",
"member_id": "42bc01fbd89dd1d45d13506933f6f4fc"
}
The set of fields, their types, and their purpose are described in Returned Data of BX24.getAuth.
Error Handling
The function has no error codes of its own: it does not call the REST API. In case of any failure, the handler does not run.
|
Situation |
What Happens |
What to Do |
|
The function is called before the library has finished initializing |
The call is silently ignored: no request is sent, |
Move the call into the BX24.init handler |
|
Bitrix24 could not issue a new token — for example, the application's trial or paid period has ended |
Bitrix24 shows a browser |
Check the application status in Bitrix24. Provide for the application behavior in case the handler does not run |
|
The page is opened outside the application frame |
The library does not initialize: on load it throws the exception |
Open the page as a Bitrix24 application |