Authorization of third-party web-applications¶
Opening authorization dialogue¶
In order to authorize the user, you must redirect their browser to URL https://www.admitad.com/api/authorize/ using the data format application/x-www-form-urlencoded and transmitting the following parameters:
Name
Required
Description
client_id ✔ ID of your application.*
redirect_uri ✔ 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).
state 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.
scope ✔ A list of application access settings separated by a space that shall be requested.
response_type ✔ Type of response you would like to get - code
* The app ID is available for the authorized user in their personal account (by clicking the “Show credentials” button).
Example of a request:
https://www.admitad.com/api/authorize/?scope=advertiser_statistics advertiser_websites advertiser_info&state=7c232ff20e64432fbe071228c0779f&redirect_uri=https://admitad.com/&response_type=code&client_id=cb281d918a37e346b45e9aea1c6eb7If the user is not logged in, they will see a dialogue box offering to enter login and password.
Granting access rights¶
After logging 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 tokencode
will be transferred in GET parameter to the specified address:https://redirect_uri/?state=7c232ff20e64432fbe071228c0779f&code=c75ebf64ad48a352630b6d953ce365In case of an error, the user’s browser will be redirected with the error code and description:
https://redirect_uri/?state=7c232ff20e64432fbe071228c0779f&error_description=client_id+cb281d918a37e346b45e9aea1c6eb7+doesn't+exist&error=invalid_client
Getting access_token
¶
To get
access_token
it is required to send POST request to URL https://api.admitad.com/token/ using data format application/x-www-form-urlencoded and transfer the following parameters:
Name
Required
Description
client_id ✔ ID of your application.*
client_secret ✔ Secret key of your application
code ✔ The code received at the previous stage of authorization (parameter redirect_uri).
grant_type ✔
- Request type
- authorization_code
redirect_uri ✔ 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*
andclient_secret*
as access settings. The header of authorization is a base64-encoded string that contains colon-concatenatedclient_id
andclient_secret
.
* The app ID (client_id) and secret key (client_secret) are available for the authorized user at the homepage for developers (by clicking the “Get keys” button).
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 client_id='cb281d918a37e346b45e9aea1c6eb7' client_secret='a0f8a8b24de8b8182a0ddd2e89f5b1' 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):
Y2IyODFkOTE4YTM3ZTM0NmI0NWU5YWVhMWM2ZWI3OmEwZjhhOGIyNGRlOGI4MTgyYTBkZGQyZTg5ZjViMQ==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 https://api.admitad.com/token/ -d 'code=c75ebf64ad48a352630b6d953ce365&client_secret=a0f8a8b24de8b8182a0ddd2e89f5b1&grant_type=authorization_code&client_id=cb281d918a37e346b45e9aea1c6eb7&redirect_uri=https%3A%2F%2Fadmitad.com%2F'Example of a request:
POST /token/ HTTP/1.1 Host: api.admitad.com Content-Type: application/x-www-form-urlencoded;charset=UTF-8 code=c75ebf64ad48a352630b6d953ce365&client_secret=a0f8a8b24de8b8182a0ddd2e89f5b1&grant_type=authorization_code&client_id=cb281d918a37e346b45e9aea1c6eb7&redirect_uri=https%3A%2F%2Fadmitad.com%2FAs a result of this request you will get a new
access_token
. The time to live of the token in secondsexpires_in
,refresh_token
and additional information for users are updated as well:{ "username": "advertiser1", "first_name": "name", "last_name"': "surname", "language": "en", "access_token": "4b8b33955a", "token_type": "bearer", "expires_in": 604800, "refresh_token": "ea957cce42", "scope": "advertiser_statistics advertiser_websites advertiser_info" }