Event When Creating an Application System User ONAPPUSERREADY

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

Scope: basic

Who can subscribe: any user

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

The handler is transferred together with the application configuration.

Both events, ONAPPUSERREADY and ONAPPINSTALL, are triggered when the installation is completed, including after the installFinish call. There are two differences: the ONAPPUSERREADY handler is registered automatically for any application with an installation URL, and the event data contains long-lived authorization of 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 transmitted as a POST request

{
            "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": "P",
                "date_finish": "1767139200",
                "LANGUAGE_ID": "de"
            },
            "ts": "1756890123",
            "auth": {
                "access_token": "u9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4",
                "refresh_token": "q9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4",
                "expires_in": "3600",
                "scope": "crm,user,task",
                "domain": "some-domain.bitrix24.com",
                "server_endpoint": "https://oauth.bitrix.info/rest/",
                "client_endpoint": "https://some-domain.bitrix24.com/rest/",
                "member_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
                "user_id": "1",
                "status": "P",
                "application_token": "0f1e2d3c4b5a69788796a5b4c3d2e1f0"
            }
        }

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 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:

  • F — free mass-market application
  • D — demo version of a mass-market application
  • T — trial version of a mass-market application, time-limited
  • P — paid mass-market application

LANGUAGE_ID*
string

Default language of the Bitrix24 account: ru, en and others

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

Codes of the permissions granted to the application, separated by commas

domain*
string

Address of the Bitrix24 account where the event occurred

server_endpoint*
string

Authorization server address for token renewal

client_endpoint*
string

Base path for calling Bitrix24 API methods

member_id*
string

Unique identifier of the account

user_id*
integer

ID of the employee who installed the application

status
string

Application status.

Possible values:

  • F — free mass-market application
  • D — demo version of a mass-market application
  • T — trial version of a mass-market application, time-limited
  • P — paid mass-market application

application_token*
string

Application token. Compare it with the token retained during installation to make sure the request came from Bitrix24. For more details, see the article Security in Handlers

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