Authorization of third-party web-applications

Opening authorization dialogue

To authorize the user, it is necessary to redirect the user’s browser on URL, using application/x-www-form-urlencoded data format and transmit the following parameters:





ID of your application.*


URL to which the user will be redirected after authorization (the domain of the specified URL shall comply with the primary domain in the settings of the application).


The value used by the client to check the state between request and response of the server. The server returns this value when it redirects the user agent back to the client


A list of application access settings separated by a space that shall be requested.


Type of response you would like to get.

Example of request: arecords banners websites&state=7c232ff20e64432fbe071228c0779f&redirect_uri=

If the user is not logged in, a dialogue box will be displayed offering to enter login and password.

Granting access rights

When logged in the user will be offered to authorize the application by providing access to required settings requested by means of parameter scope. A complete list of settings is available in the section of application access rights.

Getting code parameter

Upon successful app authorization the user’s browser will be redirected to redirect_uri, the URL specified when the authorization dialogue appears. The code to get an access token code will be transferred in GET-parameter to the specified address:


In case of an error, the user’s browser will be redirected with the error code and description:


Getting access_token

To get access_token it is required to send POST request to URL using data format application/x-www-form-urlencoded and transfer the following parameters:





ID of your application.*


Secret key of your application


The code received at the previous stage of authorization (parameter redirect_uri).

Type of request
  • authorization_code

Address, to which the user will be re-addressed after authentication (the domain of the indicated address must correspond to the main domain in the application settings).

The request should use HTTP Basic authentification with the use of client_id* and client_secret* as access settings. The header of authorization is a base64-encoded string that contains colon-concatenated client_id and client_secret.

  • * The identifier (client_id) and the secret key (client_secret) of the application are available for the logged in publisher at the homepage for developers (when the “Get keys” button is clicked).

Below is an example of forming a base64-encoded authorization header in Python 2.7 for client_id=’cb281d918a37e346b45e9aea1c6eb7’ and client_secret=’a0f8a8b24de8b8182a0ddd2e89f5b1’:

from base64 import b64encode
data = client_id + ':' + client_secret
# data = 'cb281d918a37e346b45e9aea1c6eb7:a0f8a8b24de8b8182a0ddd2e89f5b1'
data_b64_encoded = b64encode(data)

Below is an example of a base64-encoded authorization header (the data_b64_encoded variable):


Below is an example of a request using a curl utility for client_id=cb281d918a37e346b45e9aea1c6eb7, where b64XXX is the base64-encoded authorization header:

curl -H 'Authorization: Basic b64XXX' -X POST -d 'code=c75ebf64ad48a352630b6d953ce365&client_secret=a0f8a8b24de8b8182a0ddd2e89f5b1&grant_type=authorization_code&client_id=cb281d918a37e346b45e9aea1c6eb7&'

Example of request:

POST /token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=UTF-8


As a result of this request you will get a new access_token. The time to live of the token in seconds expires_in, refresh_token and additional information for users are returned as well:

    "username": "webmaster1",
    "first_name": "name",
    "last_name"': "surname",
    "language": "ru",
    "access_token": "4b8b33955a",
    "token_type": "bearer",
    "expires_in": 604800,
    "refresh_token": "ea957cce42",
    "scope": "advcampaigns arecords banners websites"