Bitrix24 Applications

Simplified token retrieval

The simplest scenario for getting access to REST API is having an application within Bitrix24 interface. In this case, all required authorization data is issued to the app when it is opened. Also, JS library can be used for executing API calls.

Application gets the following array of POST data:

array (
  'DOMAIN' => 'portal.bitrix24.com', // account's domain
  'PROTOCOL' => '1', // query protocol: 0 - http, 1 - https
  'LANG' => 'en', // current language, used when viewing the account
  'APP_SID' => 'dd8cec11e347088fe87c44870a9f1dba', // service parameter for connecting JS library with app's environment
  'AUTH_ID' => 'ahodg4h37n89vo17gbkgq0x1l825nnb5', // main authorization token required for accessing REST API
  'AUTH_EXPIRES' => '3600', // authorization token lifetime
  'REFRESH_ID' => '2lg086mxijlpvwh0h7r4nl19udm4try5', // additional authorization token used for extending saved authorization
  'member_id' => 'a223c6b3710f85df22e9377d6c4f7553', // unique account's identification number independent from domain name
  'status' => 'P', // app status at the account. Its value is used exclusively for providing information. Use method oauth.bitrix.info/rest/app.info for getting trusted value. 
)

API requests can be directly executed via the parameter AUTH_ID.

And as mentioned above, applications within the interface can query API at the client's side (i. e. user browser) by connecting JS library and using methods BX24.callMethod and BX24.callBatch. Authorization is handled automatically in this case.

Consequently a simple scenario for getting user authorization tokens becomes available when installing the application. As was demonstrated in this example inside "Quick start" section, public application can have a dedicated installation script displayed once in the a frame to the user at the moment of app installation. Bitrix24 passes the same POST query data into this frame just as in the standard case. Accordingly, installation scripts can be developed to save auth tokens (and most importantly - including the refresh_token) at the app's side to further implement automatic token refresh scenario.

App installation event

Next authorization method below is available for applications that don't have a page within Bitrix24 interface (parameter Use Rest API in the app's edit form in the partner's account or at Bitrix24 account). The app verson's edit form (or in the account's local app edit form) may have the parameter Link-callback for installation event. Specify a link to event handler in this field, when installing the application, the handler will receive POST query with the data as follows (application/x-www-form-urlencoded):

array(
  'event' => 'ONAPPINSTALL',
  'data' => array(
    'VERSION' => '1',
    'LANGUAGE_ID' => 'en',
  ),
  'ts' => '1466439714',
  'auth' => array(
    'access_token' => 's6p6eclrvim6da22ft9ch94ekreb52lv',
    'expires_in' => '3600',
    'scope' => 'entity,im',
    'domain' => 'portal.bitrix24.com',
    'server_endpoint' => 'https://oauth.bitrix.info/rest/',
    'status' => 'F',
    'client_endpoint' => 'https://portal.bitrix24.com/rest/',
    'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
    'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8',
    'application_token' => '51856fefc120afa4b628cc82d3935cce',
  ),
)

Query field contain event (event), event data (data), as well as authorisation data for accessing REST API (auth) on behalf of user who installed the app.

Main parameters:

• access_token - main authorization token required for accessing REST API;
• refresh_token - additional authorization token for extending saved authorization period;
• client_endpoint - address for account's REST interface ;
• server_endpoint - address for server's REST interface;
• status - application status at the account.

See Events