Documentation
New REST documentation is now available. Detailed descriptions, more listed examples and a convenient search feature.
Go

Examples

Example 1

Problem: get the list of all REST methods available at my.bitrix24.com.

  • Assume the application sends the following requests: 
    "CLIENT_ID" => 'First_APP',
"CLIENT_SECRET" => 'secret_key',
"TITLE" => 'Test app',
"REDIRECT_URI" => ' http://test.com/bitrix/oauth/oauth_test.php',
"SCOPE" => array('user')
    Here:
    • CLIENT_ID – the application ID;
    • CLIENT_SECRET – the secret key to sing requests;
    • TITLE – the application name;
    • REDIRECT_URI – the URL of a script that will receive and process the server response;
    • SCOPE - an array containing permissions available to the application.
  • Obtain the first key (Request token). The application will have to redirect a user to:

    http://my.bitrix24.com/oauth/authorize/?client_id=First_APP&response_type=code&redirect_uri= http%3A%2F%2Ftest.com%2Fbitrix%2Foauth%2Foauth_test.php

    Here:
    • my.bitrix24.com – the remote server address;
    • client_id – the application ID;
    • response_type – specifies the type of the response data (we want "code");
    • redirect_uri – specifies the encoded URL of your script that will receive and process the server response. The URL must be the same you provided when registering the application.

    If the user is not logged in, they will see the authentication form. If the user has been or is being authenticated, the server will redirect to REDIRECT_URI with the initial authentication token:

    https://test.com/bitrix/oauth/oauth_test.php?code=xxxxxxxxxxxxxxxxxxxxxxxxxxx

    Here:
    • code– request token returned by the server (the token default lifetime is 30 sec).
  • The script looks at the code parameter and requests the second key (access token) by sending a GET request to:

    http://my.bitrix24.com/oauth/token/?client_id=First_APP&grant_type=authorization_code&client_secret=secret_key&redirect_uri=http%3A%2F%2Ftest.com%2Fbitrix%2Foauth%2Foauth_test.php&code= xxxxxxxxxxxxxxxxxxxxxxxxxxx&scope=user

    Here:
    • my.bitrix24.com – the remote server address;
    • client_id – the application ID;
    • grant_type – specifies the expected key type ("authorization_code");
    • client_secret – the application secret key;
    • redirect_uri – specifies the encoded URL of your script that will receive and process the server response (the same used when registering the application);
    • code – the request token obtained by the previous call;
    • scope – a list of permissions for the requested key.
  • The server will return the following data:
    • access_token – an access token provided by the server;
    • expires_in – lifespan of the access token (1 hour by default);
    • refresh_token – a special value to get the new access_token;
    • member_id – the unique Bitrix24 portal ID.
  • Now that we have the access token we can call REST API:

    http://my.bitrix24.com/rest/methods.json?auth=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy&full=true

    Here:
    • methods.json is a REST API factory method that returns a list of all available methods in JSON format.
    • auth – the access token returned by the server.
  • REST API factory will return the list, something like this: 
    {"result":["methods","batch","calendar.event.get","calendar.event.add","calendar.event.update","calendar.event.delete","calendar.event.get.nearest","calendar.section.get","calendar.section.add","calendar.section.update","calendar.section.delete","calendar.meeting.status.set","calendar.meeting.status.get","calendar.meeting.params.set","calendar.accessibility.get","calendar.settings.get","calendar.settings.set","calendar.user.settings.get","calendar.user.settings.set","notify","department.fields","department.get","entity.add","entity.get","entity.update","entity.delete","entity.rights","entity.section.add","entity.section.get","entity.section.update","entity.section.delete","entity.item.add","entity.item.get","entity.item.update","entity.item.delete","entity.item.property.add","entity.item.property.get","entity.item.property.update","entity.item.property.delete","task.ctaskitem.getmanifest","task.item.getmanifest","task.ctaskitem.add","task.item.add","task.ctaskitem.getexecutiveuserid","task.item.getexecutiveuserid","task.ctaskitem.getdata","task.item.getdata","task.ctaskitem.getdescription","task.item.getdescription","task.ctaskitem.getfiles…]}

Example 2

Problem: obtain the ID's of all task a current user planned for today.

  • To use the Tasks module, a registered application must be granted the appropriate permission (scope). 
       	"CLIENT_ID" => 'Tasks_APP',
	"CLIENT_SECRET" => 'very_secret_key',
	"TITLE" => 'Task test app',
	"REDIRECT_URI" => ' http://test.com/bitrix/oauth/oauth_test.php',
	"SCOPE" => array('task', 'user')
    Here:
    • SCOPE – specifies permissions required by the application;
  • Get the first key (request token). Send a GET request to:

    http://my.bitrix24.com/oauth/authorize/?client_id=Tasks_APP&response_type=code&redirect_uri=http%3A%2F%2Ftest.com%2Fbitrix%2Foauth%2Foauth_test.php

  • To return the result, the server will call a script at REDIRECT_URI:

    http://test.com/bitrix/oauth/oauth_test.php?code=xxxxxxxxxxxxxxxxxxxxxxxxxxx

  • The script reads the code parameter value and asks for the second key (access token) by sending another GET request:

    http://my.bitrix24.com/oauth/token/?client_id=Tasks_APP&grant_type=authorization_code&client_secret=very_secret_key&redirect_uri=http%3A%2F%2Ftest.com%2Fbitrix%2Foauth%2Foauth_test.php&code= xxxxxxxxxxxxxxxxxxxxxxxxxxx&scope=user,task

  • Again, the server replies with the result by calling REDIRECT_URI:

    http://test.com/bitrix/oauth/oauth_test.php?access_token=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy&expires_in=3600&refresh_token=zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz

    Here:
    • expires_in – the access token lifetime, seconds;
    • refresh_token – the key to refresh the access token when lifetime has expired.
  • Now that we have access_token we can call REST API:

    http://my.bitrix24.com/rest/task.planner.getlist?auth=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

  • In response, we get the task ID's: 
    [result] => Array ( [0] => 3 [1] => 4 )

    The access token can be used as many times as needed as long as it is alive. Once the access token has expired, the server will return an expired_token error. To get a new key, send the refresh token to the server:

    http://my.bitrix24.com/oauth/token/?client_id=Tasks_APP&grant_type=refresh_token&client_secret=very_secret_key&redirect_uri=http%3A%2F%2Ftest.com%2Fbitrix%2Foauth%2Foauth_test.php&refresh_token=zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz

    As before, the server will response by calling the script with the "access_token" parameter:

    http://test.com/bitrix/oauth/oauth_test.php?access_token=wwwwwwwwwwwwwwwwwwwwwwwwww&expires_in=3600


© «Bitrix24», 2001-2024