Simplified Method for Obtaining OAuth 2.0 Tokens
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
An application that opens in a frame inside the Bitrix24 interface does not need to go through the complete authorization protocol. Bitrix24 passes ready-made tokens itself every time the application opens.
The tokens are issued for the user who opened the application and are limited by their permissions in Bitrix24.
What the Application Receives on Opening
Bitrix24 contacts the application address with a POST request: some parameters arrive in the query string of the address, the rest — in the request body.
Array
(
[DOMAIN] => portal.bitrix24.com
[PROTOCOL] => 1
[LANG] => en
[APP_SID] => dd8cec11e347088fe87c44870a9f1dba
[AUTH_ID] => ahodg4h37n89vo17gbkgq0x1l825nnb5
[AUTH_EXPIRES] => 3600
[REFRESH_ID] => 2lg086mxijlpvwh0h7r4nl19udm4try5
[SERVER_ENDPOINT] => https://oauth.bitrix.info/rest/
[APPLICATION_TOKEN] => ec1b2074a9d3f5c81b6e40d27a95cf38
[APPLICATION_SCOPE] => crm,entity,im,task
[member_id] => a223c6b3710f85df22e9377d6c4f7553
[status] => F
[PLACEMENT] => DEFAULT
)
Parameters in the Query String of the Application Address
|
Parameter |
Description |
|
DOMAIN |
The address of the Bitrix24 where the application is open |
|
PROTOCOL |
The access protocol:
|
|
LANG |
The interface language of the user who opened the application. You can localize the application's own interface based on it |
|
APP_SID |
The application session identifier. Bitrix24 generates a new one each time the application is rendered and uses it to link the js library with the application environment |
Parameters in the POST Request Body
|
Parameter |
Description |
|
AUTH_ID |
The main authorization token for accessing the REST API. The same as |
|
AUTH_EXPIRES |
The lifetime of |
|
REFRESH_ID |
The authorization renewal token. The same as |
|
SERVER_ENDPOINT |
The address of the authorization server that the application contacts for a new pair of tokens |
|
APPLICATION_TOKEN |
The application token. The handler can use it to verify that the request came from Bitrix24. The same value arrives in the |
|
APPLICATION_SCOPE |
A comma-separated list of scopes granted to the application |
|
member_id |
The unique identifier of Bitrix24, independent of the domain name |
|
status |
The status of the application:
|
|
PLACEMENT |
The placement code. For the main application page it is |
Note
The status value is informational. To obtain a trusted status, call the app.info method on the authorization server: oauth.bitrix.info/rest/app.info
How to Use the Received Tokens
With the AUTH_ID value, you can call REST API methods right away — pass it in the auth parameter.
https://portal.bitrix24.com/rest/crm.deal.list?auth=ahodg4h37n89vo17gbkgq0x1l825nnb5
An application in a frame can also call methods on the browser side — through the js library, using the BX24.callMethod and BX24.callBatch methods. The library substitutes the authorization itself.
AUTH_ID lives for one hour, so for background work without the user, retain REFRESH_ID — the application uses it to obtain a new pair of tokens, see OAuth 2.0 Token Automatic Renewal.
Tokens on Application Installation
A separate installation script is specified in the settings of a local or mass-market application. It is shown to the user in a frame once, at the moment of installation, and receives the same data as a regular application page:
Retain both tokens in the installation script, above all REFRESH_ID — then the application will be able to work with the REST API after the user closes the frame.
Tokens for an Application Without an Interface
An application that works only through the API has no page in a frame, which means there is no moment when Bitrix24 passes the tokens on opening. Such an application receives the tokens at the handler specified in its settings: Bitrix24 contacts the handler immediately after the installation and passes the auth object with both tokens. The tokens are issued for the user who installed the application.
The data arrives in the body of a POST request in the application/x-www-form-urlencoded format, with nested objects as fields with square brackets. The handler reads them as ordinary form fields, and there is no need to parse JSON.
$auth = $_POST['auth'] ?? [];
$refreshToken = $auth['refresh_token'] ?? null;
Event handlers usually do not receive refresh_token. The ONAPPINSTALL event is an exception: access can be renewed only with the token from this event.
How to set up the handler and what to retain in it is described in the articles on the installation callback — for a local and for a mass-market application. The composition of the request data is covered on the page of the OnAppInstall event.
Warning
The event may arrive with a delay, so it is unreliable as the only source of tokens. If you need the tokens immediately after the installation, duplicate their retrieval using one of the methods above.
What to Do Next
- renew access with the retained
REFRESH_ID— OAuth 2.0 Token Automatic Renewal - obtain tokens for an application outside the Bitrix24 interface — Complete OAuth 2.0 Authorization Protocol
- call a method with the received token — How to Call REST API Methods