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 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 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.- 1.
- 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.
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
, orGET /v1/datamarts/:datamartId/user_points/email_hash=:emailHash/user_segments
orGET /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. |
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)
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.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
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=
.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)
}
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)
}
Last modified 1yr ago