3. Authentication

3.1. JWT

We use JWT (https://jwt.io/) and expect tokens in the Header X-Auth-Token

You will receive your unique partnerID and an optional partnerSECRET, depending on integration type.

Please use HS256 as algorithm for the signature generation.

You also have to create and provide a nonce for each generated token and create the signature with the partnerSecret+nonce.

So if your partnerSECRET is 123 and your generated nonce is abc, please sign the token with 123abc.

Token expiration is supported via the key exp in the payload and should always be used. It expects an unix timestamp as integer.

3.1.1. Token generation

We differentiate init and update tokens.

3.1.1.1. Init token

This token is on the scope of a partner and can create new leads.

PHP generation example

<?php

// supplied from maklaro
$sharedSecret = 'ASDF';
$partnerId = 'XYZ';

// jwt generation
$nonce = sha1(mt_rand(100000,999999).time());
$timestamp = date('Y-m-d H:i:s', time());
$exp = time() + (2 * 24*60*60); // token will expire in 2 days

$payload = array(
    'type' => 'init',
    'nonce' => $nonce,
    'partner_id' => $partnerId,
    'timestamp' => $timestamp,
    'exp' => $exp
);

// attach nonce to shared secret
$secret = $sharedSecret.$nonce;

// composer require firebase/php-jwt
$token = \Firebase\JWT\JWT::encode($payload, $secret);

3.1.1.2. Update token

This token is on the scope of one lead and such has to provide lead_id and lead_token. This is only needed if you want to update or expand the data of one lead in the Maklaro system. lead_id and lead_token would be provided by Maklaro after a lead was created and pushed to you / your system / your CRM. In most implementations this is not needed and can be skipped.

PHP generation example

<?php

// supplied from maklaro
$sharedSecret = 'ASDF';
$partnerId = 'XYZ';

// supplied via token received from update request, or pushed to partners
$leadId = '123';
$leadToken = '456';

// jwt generation
$nonce = sha1(mt_rand(100000,999999).time());
$timestamp = date('Y-m-d H:i:s', time());
$exp = time() + 60;   // token will expire in 1 minute

$payload = array(
    'type' => 'update',
    'nonce' => $nonce,
    'partner_id' => $partnerId,
    'timestamp' => $timestamp,
    'lead_id' => $leadId,
    'lead_token' => $leadToken,
    'exp' => $exp
);

// attach nonce to shared secret
$secret = $sharedSecret.$nonce;

// composer require firebase/php-jwt
$token = \Firebase\JWT\JWT::encode($payload, $secret);