Authentication

Choosing the authentication method

There are two ways to authenticate to the mediarithmics API:

1. Long-term API tokens

2. Signature authentication

Important: Please carefully choose the authentication method based on your use case. Choosing the wrong method can lead to significant security risks (access violation, data leakage, etc.)

Use case	Secure authentication method
Direct servers integration	Long-term API tokens
Live data collection from mobile applications	Signature authentication

Please ensure to use the right secure authentication method to avoid any security risks like access violation, data leakage, etc. For example, if you use the long-term API token into your mobile application, it could leak by decompiling the application.

Get in touch with your Account manager if you want further information on the best authentication method to pick for your needs.

Long-term API tokens

Long-term API tokens are the way to go if you plan to make server-to-server calls.

We recommend creating service accounts to bear long-term API tokens, in order to avoid cancelling your token along with deleting a regular user.

A long-term API token identifies a user 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 API token before the old one expires and update your app.

There are 2 ways you can create a long-term API token:

• In the Navigator application

• Using the API

Once generated you can use the API token in the Authorization header of all your requests.

List and create tokens in the UI

1. Head to Navigator

2. Navigate to settings

3. Then My Account > API Tokens

4. Click on the "New API Token" to generate a long-term API token

Generating using the API

POST https://api.mediarithmics.com/v1/users/:userId/api_tokens

Generates an API token for a mediarithmics user

Path Parameters

Name	Type	Description
user_id	integer	The ID of the user

Headers

Name	Type	Description
Authorization	string	Your authorization token

Request Body

Name	Type	Description
name	string	The name of the API Token

200

{
    "status":"ok",
    "data":
    {
        "id":"1438281",
        "name":"Postman",
        "creation_date":1602515387862,
        "expiration_date":1665587387862,
        "value":"token value"
    }
}

Please note that you need an other api token to generate long-term api tokens using the API. You can generate the first one in the Navigator UI.

List tokens using the API

GET https://api.mediarithmics.com/v1/users/:userId/api_tokens

Path Parameters

Name	Type	Description
user_id	string	The ID of the user

Headers

Name	Type	Description
Authorization	string	Your authorization token

200

{
    "status":"ok",
    "data":[
        {
            "id":"1483281",
            "name":"Postman",
            "creation_date":1602515387862,
            "expiration_date":1665587387862,
            "value":"api:gkqKkuXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXGcdKn7Vv9G"
        }],
    "count":1,
    "total":1,
    "first_result":0,
    "max_result":50,
    "max_results":50
}

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 or published mobile app, and the communication with the mediarithmics platform could be hacked by a man in the middle or the app decompiled. 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 UserPoint 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.

Generate a secret key

POST https://api.mediarithmics.com/v1/users/:userId/message_authentication_keys

Request Body

Name	Type	Description
scheme	string	The scheme associated with the secret key. Possible values : HMAC_SHA256
key_id	string	A unique string identifying your secret key. The API will return an error if the value is already used by another secret key. This value will be used later on when signing API calls.

Response Body

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 for iOS using Swift

import Foundation
import CryptoKit

func signPayload(uri:String, secretKeyId:String, timestamp:Int64, payload:String, secretKeyValue:String) -> String {
    let message = Data("\(uri)\n\(secretKeyId)\n\(String(timestamp))\n\(payload)".utf8)
    let symmetricKey = SymmetricKey(data: Data(secretKeyValue.utf8))
    let hmac = HMAC<SHA256>.authenticationCode(for: message, using: symmetricKey)
    let base64hmac = Data(hmac).base64EncodedString()
    return base64hmac
}

func sendUserEvent(
    userAccountId:String?,
    mobileVendorId:String?,
    mobileAdId:String?,
    eventName:String,
    category:String?,
    subCategory:String?) {
        
        // Constant parameters that could be defined in a configuration file
        let DATAMART_ID="XXX"           // the id of the database
        let APPLICATION_ID="XXX"        // the id of the mobile application
        let COMPARTMENT_ID="XXX"        // the id used to define the nature of the user account id
        let VENDOR_ID_REGISTRY_ID="XXX" // the id used to define the nature of the mobile vendor id
        let SECRET_KEY_ID="XXX" // the id of the secret key used to sign the message
        let SECRET_KEY_VALUE="ZZZZZZZZZZZZZZZZZZZZZZZZZZ" // the secret key value
        
        // The URL entry is static
        let uri = "/v1/datamarts/"+DATAMART_ID+"/user_activities"
        let url = "https://api.mediarithmics.com" + uri
        let timestamp = Int64(Date().timeIntervalSince1970 * 1000)
        
        // Prepare the json payload
        var identifiers:[[String:Any]]  = []
        if let getUserAccountId = userAccountId  { identifiers.append(["$type":"USER_ACCOUNT", "$compartment_id":COMPARTMENT_ID, "$user_account_id": getUserAccountId ]) }
        if let getMobileVendorId = mobileVendorId  { identifiers.append(["$type":"USER_AGENT", "$user_agent_id": ("mov:ios:" + VENDOR_ID_REGISTRY_ID + ":" + getMobileVendorId) ]) }
        if let getMobileAdId = mobileAdId  { identifiers.append(["$type":"USER_AGENT", "$user_agent_id": ("mob:ios:raw:" + getMobileAdId) ]) }
        
        let jsonPayload: [String: Any] = [
            "$type": "APP_VISIT",
            "$app_id": APPLICATION_ID,
            "$session_status": "IN_SESSION",
            "$ts" : timestamp,
            "$user_identifiers" : identifiers,
            "$user_agent_info" : [
                "$initial_ts": 1759742895725,
                "$form_factor": "SMARTPHONE",
                "$os_family": "IOS",
                "$browser_family": "CHROME",
                "$browser_version": "141.0.0.0",
                "$brand": "Apple",
                "$model": "Iphone 14",
                "$os_version": "IOS26",
                "$carrier": "AT&T",
                "$raw_value": nil,
                "$agent_type": "MOBILE_APP"
                ],
            "$events":[[
                "$event_name" : eventName,
                "$ts" : timestamp,
                "$properties" : [
                    "category" : category ?? nil,
                    "sub_category" : subCategory ?? nil ]]]]
        
        // Create a URLRequest with the specified URL
        var request = URLRequest(url: URL(string:url)!)
        
        do {
            // Set the HTTP method
            request.httpMethod = "POST"
            
            // Convert the dictionary to JSON data
            let jsonData = try JSONSerialization.data(withJSONObject: jsonPayload, options: [])
            request.httpBody = jsonData
            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
            
            // Build the HMAC signature
            let base64hmac = signPayload(uri:uri, secretKeyId: SECRET_KEY_ID, timestamp: timestamp, payload: String(data:jsonData, encoding: .utf8)!, secretKeyValue: SECRET_KEY_VALUE)
            
            // Set the specific headers
            request.setValue(SECRET_KEY_ID, forHTTPHeaderField: "X-Mics-Key-Id")
            request.setValue(String(timestamp), forHTTPHeaderField: "X-Mics-Ts")
            request.setValue(base64hmac, forHTTPHeaderField: "X-Mics-Mac")
            
        } catch {
            print("Error while building the request data: \(error)")
            return
        }
        
        // Create a URLSession task to perform the API call
        let task = URLSession.shared.dataTask(with: request) { data, response, error in
            // Check for errors
            if let error = error {
                print("Error: \(error)")
                return
            }
            
            // Check for a valid HTTP response
            guard let httpResponse = response as? HTTPURLResponse else {
                print("Invalid HTTP response")
                return
            }
            
            // Check for a successful status code (e.g., 200 OK)
            if httpResponse.statusCode == 200 {
                let responseDataString = data.flatMap { String(data: $0, encoding: .utf8) } ?? "No response data"
                print("HTTP Response OK!, body:\(responseDataString) ")
            } else {
                let responseDataString = data.flatMap { String(data: $0, encoding: .utf8) } ?? "No response data"
                print("HTTP Response Error: \(httpResponse.statusCode)\n\(responseDataString)")
                return
            }
        }
        
        // Start the URLSession task
        task.resume()
}

Posting activities for Android using Kotlin

import java.io.DataOutputStream
import java.net.HttpURLConnection
import java.net.URL
import java.util.*
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec


fun signPayload(uri: String, secretKeyId: String, timestamp: Long, payload: String, secretKeyValue: String): String {
    val message = "$uri\n$secretKeyId\n$timestamp\n$payload".toByteArray(Charsets.UTF_8)
    val secretKey = SecretKeySpec(secretKeyValue.toByteArray(Charsets.UTF_8), "HmacSHA256")
    val hmac = Mac.getInstance("HmacSHA256").apply { init(secretKey) }.doFinal(message)
    return Base64.getEncoder().encodeToString(hmac)
}

fun sendUserEvent(
    userAccountId: String?,
    userVendorId: String?,
    userMobileAdId: String?,
    eventName: String,
    category: String?,
    subCategory: String?
) {

    // Constant parameters that could be defined in a configuration file
    val DATAMART_ID = "XXX"          // the id of the database
    val APPLICATION_ID = "XXX"       // the id of the mobile application
    val COMPARTMENT_ID = "XXX"       // the id used to define the nature of the user account id
    val SECRET_KEY_ID = "XXXX" // the id of the secret key used to sign the message
    val SECRET_KEY_VALUE = "ZZZZZZZZ" // the secret key value

    // The URL entry is static
    val uri = "/v1/datamarts/$DATAMART_ID/user_activities"
    val url = "https://api.mediarithmics.com$uri"
    val timestamp = System.currentTimeMillis()

    // Prepare the JSON payload
    val identifiers = mutableListOf<String>()
    userAccountId?.let { it -> identifiers.add(""" { "${'$'}type" : "USER_ACCOUNT" , "${'$'}compartment_id" : "$COMPARTMENT_ID", "${'$'}user_account_id" : "$it" }""") }

    val jsonPayload = """{
            "${'$'}type" : "APP_VISIT",
            "${'$'}app_id" : "$APPLICATION_ID",
            "${'$'}session_status" : "IN_SESSION",
            "${'$'}ts" : $timestamp,
            "${'$'}user_identifiers" : ${identifiers.toList().joinToString(",", "[", "]")},
            "${'$'}user_agent_info" : {
                "${'$'}initial_ts": 1759742895725,
                "${'$'}form_factor": "SMARTPHONE",
                "${'$'}os_family": "ANDROID",
                "${'$'}browser_family": "CHROME",
                "${'$'}browser_version": "141.0.0.0",
                "${'$'}brand": "SAMSUNG",
                "${'$'}model": "GALAXY S20",
                "${'$'}os_version": "ANDROID 15",
                "${'$'}carrier": "AT&T",
                "${'$'}raw_value": null,
                "${'$'}agent_type": "MOBILE_APP"
            },
            "${'$'}events" : [
                    {
                            "${'$'}event_name" : "$eventName",
                            "${'$'}ts" : $timestamp,
                            "${'$'}properties" : {
                                    "category" : ${if (category == null) "null" else "\"${category}\""},
                                    "sub_category" : ${if (subCategory == null) "null" else "\"${subCategory}\""}
                            }
                    }
            ]
    }"""

    // Create a HttpURLConnection with the specified URL
    val urlConnection = URL(url).openConnection() as HttpURLConnection

    try {
        // Set the HTTP method
        urlConnection.requestMethod = "POST"

        // Enable output streams
        urlConnection.doOutput = true
        urlConnection.doInput = true

        // Convert the map to JSON data
        val jsonData = jsonPayload.toString().toByteArray(Charsets.UTF_8)

        urlConnection.setRequestProperty("charset", "utf-8")
        urlConnection.setRequestProperty("Content-Type", "application/json")
        urlConnection.setRequestProperty("Content-length", jsonData.size.toString())

        println(jsonData.toString(Charsets.UTF_8))
        // Build the HMAC signature
        val base64hmac = signPayload(uri, SECRET_KEY_ID, timestamp, String(jsonData, Charsets.UTF_8), SECRET_KEY_VALUE)

        // Set the specific headers
        urlConnection.setRequestProperty("X-Mics-Key-Id", SECRET_KEY_ID)
        urlConnection.setRequestProperty("X-Mics-Ts", timestamp.toString())
        urlConnection.setRequestProperty("X-Mics-Mac", base64hmac)

        //urlConnection.disconnect()

        val outputStream: DataOutputStream = DataOutputStream(urlConnection.outputStream)
        outputStream.write(jsonData)
        outputStream.flush()
        
    } catch (e: Exception) {
        println("Error while building the request data: $e")
        return
    }

    // Perform the API call
    try {
        val responseCode = urlConnection.responseCode
        // Check for a successful status code (e.g., 200 OK)
        if (responseCode == 200) {
            val responseDataString = urlConnection.inputStream.bufferedReader().use { it.readText() }
            println("HTTP Response OK!, body: $responseDataString")
        } else {
            val responseDataString = urlConnection.errorStream.bufferedReader().use { it.readText() }
            println("HTTP Response Error: $responseCode\n$responseDataString")
        }
    } catch (e: Exception) {
        println("Error: $e")
    } finally {
        // Disconnect after the request is complete
        urlConnection.disconnect()
    }
}

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,
    "$user_agent_info" : {
        "$initial_ts": 1759742895725,
        "$form_factor": "SMARTPHONE",
        "$os_family": "IOS",
        "$browser_family": "CHROME",
        "$browser_version": "141.0.0.0",
        "$brand": "Apple",
        "$model": "Iphone 14",
        "$os_version": "IOS26",
        "$carrier": "AT&T",
        "$raw_value": null,
        "$agent_type": "MOBILE_APP"
    },
    "$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)
}