1. Improve Digital Help Centre
  2. Publishers & Supply Partners
  3. Publisher API

Client authentication

Overview

This article details the method of authenticating in order to access Publisher API Services.

 

Introduction

Improve Digital 360 API is using OAuth2 system for authentication, defined in RFC-6749. OAUth2 authorization server is hosted as a part of the platform and has made accessible its public endpoints to all clients. For 3rd party API clients we support grant type.

All OAuth2 related requests (token requests) require OAuth2 client authentication. All other API calls require OAuth2 Bearer token authentication, using the obtained access token, as per RFC-6750.

 

OAuth2 operations

All OAuth2 related requests are made over a secure channel (HTTPS) and must be authenticated with OAuth2 client credentials. Client should supply credentials either using HTTP/Basic authentication scheme or by supplying them as part of form data of the grant flow.

Client credentials will be issued to each customer, one for each client application. These credentials are a pair of “Client ID” and “Client Secret” and are expected to be kept safe.

If Basic authentication is used, client needs to additionally pass along an Authorization header with the bearer type as Basic and the value client_id : client_secret Base64 encoded:

Authorization: Basic Base64(client_id:client_secret)

At the time of this writing, Improve Digital OAuth2 authentication for programmatic clients supports the Client credentials grant type.

 

Client credentials grant flow

Client credentials grant flow is intended for pure machine API usage. In this case, there is no user known to the client. The client application is interacting with the 360 API directly. Client application supplies client ID and client secret when it requests a token. This token will allow the client application to perform its programmatic actions. Roles assigned to the token are defined by administrators when that client credentials are created.

Access token generated in this flow will not be accompanied with a refresh token. When access token expires, clients need to fetch another one. A sample interaction is as follows.

POST /oauth/token HTTP/1.1
Host: api.360yield.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic aW1wcm92ZS9kaWdpdGFsMDA=
Cache-Control: no-cache

grant_type=client_credentials

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Type: application/json;charset=UTF-8
Date: Fri, 20 Jan 2017 14:56:53 GMT
Expires: 0
Pragma: no-cache
transfer-encoding: chunked

{
 "value": "dda5443a-ec3a-4afb-a1c4-f2058426d15b",
 "expiration": 1484924863050,
 "tokenType": "bearer",
 "refreshToken": null,
 "scope": [
 "xxx"
 ],
 "additionalInformation": {},
 "expiresIn": 649,
 "expired": false
}

Note: the token received through https://api.360yield.com/oauth/token would need to be used in the Authorization header of each API request (other than requests sent to /oauth/token) after the keyword “Bearer”:

Authorization: Bearer theTokenThatYouReceived

When a token expires, a new one would need to be generated for new API operations.

Logout

Additional to RFC-6749, 360 API supports the ability to signal end of “session” by deleting the active access token. The REST call to 360 API is “DELETE /oauth/logout/{access_token}”. This call must also be authenticated with client’s credentials. Sample is given here:

DELETE /ouath/logout/97127282-8f28-4028-b643-e36a5d875888 HTTP/1.1
Host: api.360yield.com
Authorization: Basic aW1wcm92ZS9kaWdpdGFsMDA=

HTTP/1.1 204 No content

If the token does not exist, does not belong to the authenticated client or has already expired, the response will be “HTTP 404”.

 

360 API calls

All other 360 API calls require OAuth2 Bearer token authentication, as per RFC-6750. Every 360 API REST call must supply “Authorization” header with “Bearer” token, value is access token. A sample interaction would look like this:

GET /publisher/v2/publishers/{publisherID}/campaigns HTTP/1.1
Host: api.360yield.com
Authorization: Bearer 97127282-8f28-4028-b643-e36a5d875888
Content-Type: application/json
Accept: application/json
Accept-Language: en_GB

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Connection: keep-alive
Content-Length: 456
Content-Type: application/json;charset=UTF-8
Date: Thu, 15 Dec 2016 15:06:04 GMT
Expires: 0
Pragma: no-cache

{
 …
}

 

PHP example for the encoding

$signature = base64_encode("client_id:client_secret");
var_dump($signature);

PHP example for a token requent

<?php
$list = array(
'http' => array(
'method' => 'POST',
'header' => array(
'Authorization: Basic the_string_encoded_in_base64',
'Content-Type: application/x-www-form-urlencoded',
'Accept: application/json'
),
'content' => 'grant_type=client_credentials',
)
);
$context = stream_context_create($list);
$task = file_get_contents("https://api.360yield.com/oauth/token", false, $context);
echo $task;

Security concerns and best practices

Client credentials are issued to customers for each different application they intend to use. These credentials must be kept safe, since they authenticate client application to Improve Digital 360 API. Compromised client credentials must be communicated to Improve Digital immediately!

Improve Digital’s 360 API is accessed over a secured HTTP connection. Access token is the proof of identity and client should be careful which other clients (if any) it gives this token to. Access token has a limited lifetime decreasing the risk of damage in case of token leak, still, it should be used with care. When the access token expires, clients will need to obtain a new token.

Recommended use of tokens is:

  1. At the start of session/batch, client should authenticate and obtain access token.
  2. Client should use access token while it is alive.
  3. When the access token has expired (REST API responds with 401), client should obtain a new one.
  4. When the session is over, the client should logout and discard the token.

References