**************
Authentication
**************

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.


Token generation
~~~~~~~~~~~~~~~~

We differentiate ``init`` and ``update`` tokens.


Init token
----------

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

**PHP generation example**

.. code-block:: php

    <?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);


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**

.. code-block:: php

    <?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);