Event for Creating an Application System User ONAPPUSERREADY

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

Scope: basic

Who can subscribe: the application handler is registered automatically

The ONAPPUSERREADY event is triggered after the application installation is completed successfully, when Bitrix24 has created or reactivated the application system user.

The event handler is registered automatically at the application handler URL used for installation. The handler is transferred together with the application configuration.

Unlike ONAPPINSTALL, the ONAPPUSERREADY event is sent for both immediate and deferred installation completion modes and passes long-lived authorization for the system user. If the application needs to run without an employee's involvement, rely on the ONAPPUSERREADY event.

What the Handler Receives

Data is passed as a POST request in form-encoded format

{
            "event": "ONAPPUSERREADY",
            "event_handler_id": "17",
            "data": {
                "access_token": "s1a2b3c4d5e6f70890abcdef1234567890abcd",
                "refresh_token": "r1a2b3c4d5e6f70890abcdef1234567890abcd",
                "expires_in": "3600",
                "scope": "crm,user,task",
                "domain": "oauth.bitrix.info",
                "server_endpoint": "https://oauth.bitrix.info/rest/",
                "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                "member_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
                "user_id": "512",
                "client_id": "app.573ad8a0346747.09223434",
                "status": "L",
                "LANGUAGE_ID": "de"
            },
            "ts": "1756890123",
            "auth": {
                "access_token": "u9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4",
                "refresh_token": "q9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4",
                "expires_in": "3600",
                "scope": "crm,user,task",
                "domain": "oauth.bitrix.info",
                "server_endpoint": "https://oauth.bitrix.info/rest/",
                "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                "member_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
                "user_id": "1",
                "status": "L",
                "application_token": "0f1e2d3c4b5a69788796a5b4c3d2e1f0"
            }
        }

The data object contains the system user authorization, and the auth object contains the authorization of the employee who installed the application and the application_token for event verification.

Request Parameters

Required parameters are marked with *

Name
type

Description

event*
string

Symbolic event code.

In this case — ONAPPUSERREADY

event_handler_id
integer

Event handler ID

data*
object

Object with system user authorization parameters.

The structure is described below

ts*
timestamp

Date and time of the event sent from the event queue

auth*
object

Object containing authorization parameters and information about the Bitrix24 account where the event occurred.

The structure is described below

Parameter data

Name
type

Description

access_token*
string

System user access token

refresh_token*
string

Token for refreshing the system user authorization

expires_in*
integer

Access token lifetime in seconds

scope*
string

List of permissions granted to the application

domain*
string

Authorization server domain

server_endpoint*
string

Authorization server address for refreshing OAuth 2.0 tokens

client_endpoint*
string

Base path for calling Bitrix24 API methods

member_id*
string

Bitrix24 account ID

user_id*
integer

System user ID in Bitrix24

client_id*
string

Application ID

status*
string

Application status.

Possible values:

  • L — local application
  • S, T, D, P — mass-market application variants

LANGUAGE_ID*
string

Bitrix24 language at the time of application installation

date_finish
timestamp

Subscription end date and time, if known to Bitrix24

The APP_ID field is not passed in data. The application identifies itself by client_id and member_id.

Parameter auth

Name
type

Description

access_token*
string

Token for API calls

refresh_token*
string

Token for refreshing OAuth 2.0 authorization

expires_in*
integer

Access token lifetime in seconds

scope*
string

List of permissions granted to the application

domain*
string

Address of the Bitrix24 account where the event occurred

server_endpoint*
string

Bitrix24 authorization server address required to refresh OAuth 2.0 tokens

client_endpoint*
string

Base path for calling Bitrix24 API methods

member_id*
string

ID of the Bitrix24 account where the event occurred

user_id*
integer

ID of the employee who installed the application

status*
string

Application status.

Possible values:

  • L — local application
  • S, T, D, P — mass-market application variants

application_token*
string

Token for secure event handling

How to Handle the Event

  1. Check auth.application_token
  2. Retain data.refresh_token, data.member_id, and data.client_endpoint
  3. Refresh the access token using the standard OAuth refresh flow with the retained refresh_token
  4. Run background calls to Bitrix24 API methods under the system user authorization

Handler example:

$data = $_POST['data'] ?? [];
        $auth = $_POST['auth'] ?? [];
        
        if (($auth['application_token'] ?? '') !== $storedApplicationToken) {
            http_response_code(403);
            exit;
        }
        
        saveSystemUserAuth(
            memberId: $data['member_id'],
            domain: $data['client_endpoint'],
            userId: (int)$data['user_id'],
            accessToken: $data['access_token'],
            refreshToken: $data['refresh_token'],
            expiresIn: (int)$data['expires_in'],
        );

Continue Learning

Previous
After Successful Application Installation
Next
After Application Update