Authentication

Makaira supports three different authentication types.


HASH Based Message Authentication (HMAC)

Send the headers X-Makaira-Nonce and X-Makaira-Hash to authenticate by HMAC. This is the most common way when you access the API in a programmatic way.

To generate the headers you have to generate a unique nonce and calculate the hash by using the body and the shared secret.

public function generateSignatureHeaders($body = null, $sharedSecret)
{
    $nonce = bin2hex(random_bytes(16));
    $hash = hash_hmac('sha256', $nonce . ':' . $body, $sharedSecret);
    $headers[] = 'X-Makaira-Nonce: ' . $nonce;
    $headers[] = 'X-Makaira-Hash: ' . $hash;

    return $headers;
}
// Define nonce and shared secret
const date = new Date();
var nonce = date.toString();
var secret = <shared secret>;

// Hash calculation
var hashString = nonce + ':' + request.data;
var hash = CryptoJS.HmacSHA256(hashString, secret);

// Setting headers
const req = new XMLHttpRequest();
req.setRequestHeader("content-type","application/json");
req.setRequestHeader('X-Makaira-Hash', hash);
req.setRequestHeader('X-Makaira-Nonce', nonce);
...

The shared secret can be obtained in your Makaira account.


BasicAuth

BasicAuth is often used when applying direct curl requests as you can see in the example below.

curl -X PUT \
  https://<CUSTOMER>.makaira.io/<ROUTE> \
  -u "<login>:<password>"
curl -X PUT \
  https://<CUSTOMER>.makaira.io/<ROUTE> \
  -H 'Authorization: Basic <BASIC-AUTH> \
  -H 'Content-Type: application/json'

JSON Web Token (JWT)

Use JWTs to authenticate the API Reference with your Makaira account. As we do not provide a login endpoint that would ship the token you have to login into Makaira, do a request, and grep the token from the request(Authorization Header).

Getting the JWT from your accountGetting the JWT from your account

Getting the JWT from your account