Authentication

Search…
Authentication
There are two ways you can authenticate on the mediarithmics API:
Login / Password authentication generates a temporary access token. Best used for web applications
Long-term access tokens for any server to server integration
A third way has been created specifically for mobile apps that are collecting events: Signature authentication. It is only available for a few specific endpoints.
Temporary access tokens
Temporary access tokens are the way to go if you plan to make client-to-server calls, as using a long-term access token in your client application would not be safe.. A temporary token with an expiration delay of 1 hour is generated server-side, then passed on to the client application from which the calls will be made.
To generate your temporary access token, you need to call the /v1/access_tokens endpoint, using your mediarithmics username and password (same as the ones you use to log in).
curl --location --request POST 'https://api.mediarithmics.com/v1/authentication/access_tokens' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "<USERNAME>",
    "password": "<PASSWORD>"
}'
The response will give you an access token:
{
    "status": "ok",
    "data": {
        "access_token": "<ACCESS_TOKEN>",
        "expires_in": 3600,
        "refresh_token": null
    }
}
You then need to use the provided access token in the Authorization header of all your requests.
Long-term access tokens
Long-term access tokens are the way to go if you plan to make server-to-server calls.
We recommend creating "technical" users to bear long-term access tokens, in order to avoid cancelling your token along with deleting a regular user.
A long-term access token works as an access token but it has a longer expiration delay (usually from 12 to 24 months).
A user can have multiple long-term tokens, which can be useful to manage tokens renewal: just create a new access token before the old one expires and update your app.
There are 2 ways you can create a long-term access token:
In the Navigator application
Using the API
Once generated you can use the access token in the Authorization header of all your requests.
List and create in the UI
1.Connect to the mediarithmics platform on https://navigator.mediarithmics.com ​
2.Navigate to settings
3.Then My Account > API Tokens
4.Click on the "New API Token" to generate a long-term access token
post
https://api.mediarithmics.com
/v1/users/:userId/api_tokens
Generating using the API
Please note that you need an access token to generate long-term access tokens using the API. You can generate a temporary access token to authenticate if you don't already have a long-term token
get
https://api.mediarithmics.com
/v1/users/:userId/api_tokens
List API tokens for a user
Please note that you need an access token to list long-term access tokens using the API. You can generate a temporary access token to authenticate if you don't already have a long-term token.

You won't be able to see the complete value of the tokens using this API.
Signature authentication
The Signature authentication scheme is used in an environment where the calling part operates in a public network and the communication with the mediarithmics platform could be hacked by a man in the middle. It is the preferred choice for mobile app tracking.
Signature authentication is limited to 2 actions only:
Posting activities using the POST /v1/datamarts/${datamart_id}/user_activities endpoint
Getting user segments by user account ID, email hash or user agent ID (not user point ID) using GET /v1/datamarts/:datamartId/user_points/compartmentId=:compartmentId,user_account_id=:userAccountId/user_segments
, or GET /v1/datamarts/:datamartId/user_points/email_hash=:emailHash/user_segments or GET /v1/datamarts/:datamartId/user_points/user_agent_id=:userAgentId/user_segments endpoints
The authentication of the calling party (the mobile app) is done through a signature (Message Authentication Code) using a hashing algorithm (HMAC-SHA256).
Signature authentication is linked to a mediarithmics user. As for the API token approach, we recommend you create a technical user on mediarithmics to bear this authentication scheme.
post
https://api.mediarithmics.com
/v1/users/:userId/message_authentication_keys
Generate a secret key
Response body format:
field
type
description
id
String
Record Id
user_id
String
Id of the User linked to the secret key
creation_ts
String
Date of creation
expiration_ts
String
Date of expiration
key_id
String
A unique string identifying your secret key. Provided in the request by the user.
scheme
String enum
The scheme associated with the secret key. Possible values: HMAC_SHA256
secret_key
String enum
The value of the secret key. It has a length of 16 bytes and is provided as a hexadecimal string Warning: Store this value as the value of the secret key is only visible in the response of the creation request. In all subsequent calls, it will be obfuscated.
Usage
For each API call, a digest of the message should be calculated. Then, the 3 following headers should be contained in the API call:
X-Mics-Mac: the digest of the input data (Message Authentication Code)
X-Mics-Key-Id: the key_id of the secret key (provided by you when creating a new secret key)
X-Mics-Ts: the timestamp used in the digest (in ms)
Digest calculation
We recommend you find a library that generates digests for your platform. This library will need 2 input in order to work:
A key. You should use the secret_key provided by the platform.
A message to sign. you should generate the message from the info contained in the API call payload (see below).
The digest should be presented as a Base64 string.
Message generation
The message to sign should be generated from the following values, in this order, separated by a \n (e.g. ${uri}\n${key_id}\n${timestamp}\n${request_body}):
The uri of the API method used
The key_id value (provided by you when creating the secret key)
A timestamp (ms) generated at the time of the call
The request body as a string
Examples
Signing the message
These values:
uri: /v1/datamarts/854/user_activities
key id: my_key_identifier
timestamp: 1499103950000
request body: {\"hello\":\"world\"}
Will translate to the following message:
/v1/datamarts/854/user_activities
my_key_identifier
1499103950000
{"hello":"world"}
Therefore, the calculation of the HMAC-SHA256 of this message, with the secret key 846cee8e-5558-4ca0-b723-095aa043c6ee, base64 encoded, will be rwhKdaWtw5Hx3zjcrZDv7eO4fyNbBkIfsh2PjI+BiRE=.
Posting activities in Node.js
var rp = require('request-promise');
var crypto = require('crypto');
​
var datamart_id = 854;
var app_id = "154"; // string only
var domain = `https://api.mediarithmics.com`
var uri = `/v1/datamarts/${datamart_id}/user_activities`;
var secret_key = "846cee8e-5558-4ca0-b723-095aa043c6ee";				 
var key_id = "my_key_identifier";
var ts = 1499103950000; // in milliseconds
var test_device = {
    "os": "and",
    "aaid": "b9f47db8-c0e9-40f4-8aed-fb063d7e54f7"
};
var body = {
    "$ts": ts,
    "$type": "APP_VISIT",
    "$session_status": "IN_SESSION",
    "$user_agent_id": `mob:${test_device.os}:raw:${test_device.aaid}`,
    "$app_id": app_id,
    "$events": [{
        "$ts": ts,
        "$event_name": "my_super_event",
        "$properties": {
            "custom_property1": "value1",
            "custom_property2": "value2",
            "custom_property3": "value3",
            "custom_property4": "value4",
            "custom_property5": "value5"
        }
    }]
};
var headers = {
    "X-Mics-Key-Id": key_id,
    "X-Mics-Ts": ts
};
​
var message = uri + "\n" + key_id + "\n" + JSON.stringify(ts) + "\n" + JSON.stringify(body);
var signature = signKey(secret_key, message);
​
headers["X-Mics-Mac"] = signature;
​
console.log(`uri: ${uri}\nsecret_key: ${secret_key}\nkey_id: ${key_id}\nts: ${JSON.stringify(ts)}\nheaders: ${JSON.stringify(headers)}\nbody: ${JSON.stringify(body)}`)
console.log(`message: ${message}`);
console.log(`signature: ${signature}`);
​
postEvent(domain + uri,'POST',headers,body);
​
function signKey(clientKey, message) {
    var hash = crypto.createHmac('sha256', clientKey).update(message).digest('base64');
    return hash;
};
​
async function postEvent(uri, method, headers, body) {    
    var request = await rp({
        uri: uri,
        method: method,
        headers: headers,
        body: body,
        json: true
    });
    console.log(request)
}
Getting user segments in Node.js
var rp = require('request-promise');
var crypto = require('crypto');
​
var datamart_id = 854;
var user_agent_id = 'vec:xxx';
var domain = `https://api.mediarithmics.com`;
var uri = `/v1/datamarts/${datamart_id}/user_points/user_agent_id=${user_agent_id}/user_segments`;
var secret_key = "846cee8e-5558-4ca0-b723-095aa043c6ee";				 
var key_id = "my_key_identifier";
var ts = 1499103950000; // in milliseconds
var headers = {
    "X-Mics-Key-Id": key_id,
    "X-Mics-Ts": ts
};
​
var message = uri + "\n" + key_id + "\n" + JSON.stringify(ts);
var signature = signKey(secret_key, message);
​
headers["X-Mics-Mac"] = signature;
​
console.log(`uri: ${uri}\nsecret_key: ${secret_key}\nkey_id: ${key_id}\nts: ${JSON.stringify(ts)}\nheaders: ${JSON.stringify(headers)}`)
console.log(`message: ${message}`);
console.log(`signature: ${signature}`);
​
getEvent(domain + uri,'GET',headers);
​
function signKey(clientKey, message) {
    var hash = crypto.createHmac('sha256', clientKey).update(message).digest('base64');
    return hash;
};
​
async function getEvent(uri, method, headers) {    
    var request = await rp({
        uri: uri,
        method: method,
        headers: headers,
        json: true
    });
    console.log(request)
}