Authenticate

There are two ways to authenticate the Mediahawk REST API. Which one you use depends on your usage requirements:

Use OAuth authentication if you want to access someone else's account.
Use API Keys to access your own account.

OAuth

You can create an application that connects to Mediahawk data and authenticates as a Mediahawk user. Mediahawk supports the OAuth 2.0 Authorization Code grant type. This authentication process can be distilled into 4 steps:

Your app opens a browser window to send the user to the Mediahawk OAuth 2.0 server.
The user reviews the requested permissions and grants the app access.
The user is redirected back to the app with an authorisation code in the query string.
The app sends a request to the OAuth 2.0 server to exchange the authorisation code for an access token.

tip

Most languages will contain a package to easily authenticate OAuth, so you don't have to understand the process in detail

Prerequisites: Apply

To use OAuth you must apply to our Mediahawk Partner Programme to be approved. To apply you must provide us with the URL(s) that will be used as redirect_uris in the OAuth process which are used to validate requests. Once approved, you will be provided with a Client ID which will be used to build your OAuth application.

Step 1: Create the authorisation URL and direct the user

The first step is creating the authorisation URL. The Mediahawk authorisation URL is https://www.reports.mediahawk.co.uk/authorize. The query parameters you must pass as part of an authorisation URL are shown below. It must contain the following parameters:

response_type must equal code.
client_id your Client ID provided in prerequisites.
redirect_uri the URL to redirect the customer to on success.
state Your application should generate a random string and include it in the request. It should then check that the same value is returned after the user authorise the app. This is used to prevent CSRF attacks.

https://www.reports.mediahawk.co.uk/authorize?
response_type=code&client_id=1234567&redirect_uri=https://www.example.com&state=xyzABC

Mediahawk will prompt the user by displaying a consent screen showing the name of your application and what you will be able to access.

info

Your application doesn't do anything at this stage. Once access is granted, we will redirect the user to the authorisation URL

Step 3: Handle the response

When the user has completed the consent prompt from Step 2, we redirect the user to your authentication URL. If there are no issues and the user approves the access request, the request will contain a code as a GET parameter. If the user doesn't grant access or there is an error, you will receive a response with an error GET parameter.

https://www.example.com?code=codeReceived&state=xyzABC

Step 4: Exchange authorisation code for tokens

Once you receive the authorisation code, you are able to exchange that code for an access and refresh token by sending a URL-form encoded POST request to https://www.reports.mediahawk.co.uk/rest/v2_0/access with the values shown below:

grant_type must equal authorization_code.
code The authorisation code received from step 3.
client_id your Client ID provided in prerequisites.

CURL
PHP
Python
Node.js
C#

clientId="<CLIENT_ID>"
authorisationCode="<AUTHORISATION_CODE>"

curl -L -X POST "https://www.reports.mediahawk.co.uk/rest/v2_0/access" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=${authorisationCode}" \
--data-urlencode "client_id=${clientId}"

$clientId = "<CLIENT_ID>";
$authorisationCode = "<AUTHORISATION_CODE>";

$client = new Client();
$headers = [
  "Content-Type" => "application/x-www-form-urlencoded"
];

$options = [
"form_params" => [
  "grant_type" => "authorization_code",
  "code" => $authorisationCode,
  "client_id" => $clientId
]];
$request = new Request("POST", "https://www.reports.mediahawk.co.uk/rest/v2_0/access", $headers);
$res = $client->sendAsync($request, $options)->wait();
echo $res->getBody();

import requests

clientId = "<CLIENT_ID>"
authorisationCode = "<AUTHORISATION_CODE>"

url = "https://www.reports.mediahawk.co.uk/rest/v2_0/access"

payload="grant_type=authorization_code&code=" + authorisationCode + "&client_id=" + clientId
headers = {
  "Content-Type": "application/x-www-form-urlencoded"
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

var axios = require("axios");
var qs = require("qs");
var authorisationCode = "<CLIENT_ID>";
var clientId = "<AUTHORISATION_CODE>";

var data = qs.stringify({
  grant_type: "authorization_code",
  code: authorisationCode,
  client_id: clientId,
});
var config = {
  method: "post",
  url: "https://www.reports.mediahawk.co.uk/rest/v2_0/access",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  data: data,
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

string clientId = "<CLIENT_ID>";
string authorisationCode = "<AUTHORISATION_CODE>";

var client = new RestClient("https://www.reports.mediahawk.co.uk/rest/v2_0/access");
client.Timeout = -1;

var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("grant_type", "authorization_code");
request.AddParameter("code", authorisationCode);
request.AddParameter("client_id", clientId);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

The body of the response will be in JSON format and will contain the following:

refresh_token The refresh token to be used at a later date to refresh the access token.
access_token An access token that can be used to authenticate API requests.
token_type equals bearer.
expires_in the number of seconds until the access_token is invalidated.

info

The access token will expire after the number of seconds given in the expires_in field of the response

Using the Oauth token

Once the authorisation code flow is completed, your app is authorised to make requests on behalf of the user. To do this, provide the token as a Bearer token in the Authorization HTTP header. See the example below:

GET /rest/v2_0/numbers HTTP/1.1
Host: www.reports.mediahawk.co.uk
Accept: application/json
Authorization: Bearer <YOUR OAUTH TOKEN>

Refreshing a token

OAuth access tokens expire periodically. This is to make sure that if they're compromised, attackers will only have access for a short time. The token's lifespan in seconds is specified in the expires_in field when an authorisation code is exchanged for an access token.

Your app can exchange the received refresh token for a new access token by sending a URL-form encoded POST request to https://www.reports.mediahawk.co.uk/rest/v2_0/access with the values below.

grant_type must equal refresh_token.
refresh_token The refresh token returned in the authorisation process.
client_id your Client ID provided in prerequisites.

CURL
PHP
Python
Node.js
C#

clientId="<CLIENT_ID>"
refreshToken="<REFRESH_TOKEN>"

curl -L -X POST "https://www.reports.mediahawk.co.uk/rest/v2_0/access" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=${refreshToken}" \
--data-urlencode "client_id=${clientId}"

$clientId = "<CLIENT_ID>";
$refreshToken = "<REFRESH_TOKEN>";

$client = new Client();
$headers = [
  "Content-Type" => "application/x-www-form-urlencoded"
];
$options = [
"form_params" => [
  "grant_type" => "refresh_token",
  "refresh_token" => $refreshToken,
  "client_id" => $clientId
]];
$request = new Request("POST", "https://www.reports.mediahawk.co.uk/rest/v2_0/access", $headers);
$res = $client->sendAsync($request, $options)->wait();
echo $res->getBody();

import requests

clientId = "<CLIENT_ID>"
refreshToken = "<REFRESH_TOKEN>"

url = "https://www.reports.mediahawk.co.uk/rest/v2_0/access"

payload="grant_type=refresh_token&refresh_token=" + refreshToken + "&client_id=" + clientId
headers = {
  "Content-Type": "application/x-www-form-urlencoded"
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

var axios = require("axios");
var qs = require("qs");
var clientId = "<CLIENT_ID>";
var refreshToken = "<REFRESH_TOKEN>";

var data = qs.stringify({
  grant_type: "refresh_token",
  refresh_token: refreshToken,
  client_id: clientId,
});
var config = {
  method: "post",
  url: "https://www.reports.mediahawk.co.uk/rest/v2_0/access",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  data: data,
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

string clientId = "<CLIENT_ID>";
string refreshToken = "<REFRESH_TOKEN>";

var client = new RestClient("https://www.reports.mediahawk.co.uk/rest/v2_0/access");
client.Timeout = -1;

var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("grant_type", "refresh_token");
request.AddParameter("refresh_token", refreshToken);
request.AddParameter("client_id", clientId);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

The body of the response will be in JSON format and will contain the following:

access_token An access token that can be used to authenticate API requests.
token_type equals bearer.
expires_in the number of seconds until the access_token is invalidated.

API Keys

You can access your own account using API Keys. There are two methods:

An ApiKey header.

GET /rest/v2_0/numbers HTTP/1.1
Host: www.reports.mediahawk.co.uk
Accept: application/json
ApiKey: <YOUR API KEY>

An api_key query parameter.

https://www.reports.mediahawk.co.uk/rest/v2_0/numbers?api_key=<YOUR API KEY>

Both of these methods work in the same way. To get your API Key, please get in touch with our client services team. Once you have it, you can apply it to your requests.

Authenticate

OAuth​

Prerequisites: Apply​

Step 1: Create the authorisation URL and direct the user​

Step 2: Prompt the user for consent​

Step 3: Handle the response​

Step 4: Exchange authorisation code for tokens​

Using the Oauth token​

Refreshing a token​

API Keys​