A signature is generated by calculating a digest using the HMAC-SHA256 hashing algorithm (see more).

An HMAC is the product of a hash function applied to the body of a message along with a secret key.
So rather than sending the username and password with a web service request, it is needed to send identifier for the private key and an HMAC.

When the server receives the request, it looks up the user’s private key and uses it to create an HMAC for the incoming request. If the HMAC submitted with the request matches the one calculated by the server, then the request is authenticated.
For the signatures to match, not only must the private keys used at both ends of the transaction match, but the message body must also match exactly.

As the content is taken as a parameter for hash generating, then it is needed to pass the hash other way than within the request body. For such case, system is expecting two additional Headers: X-Public and X-Hash.

Counting the HMAC-SHA256

To generate the HMAC the private and public keys are needed. Private key is used to create the content hash and the public one is send as one of the additional headers.

See this PHP exapmle below for detail steps.

<?php
  // Variables
  $api_version = 'v1.0'; // Taken from https://api.safeguard24.eu/version
  $privateKey = 'private-key';
  $publicKey = 'public-key';
  $trailer = 'ELE78UT';

  // Prepare json request body
  $content = json_encode([
    'number' => 'ELE78UT',
    'unlock_code' => '0044161',
  ]);

  // Generate HMAC using private key
  $hash = hash_hmac('sha256', $content, $privateKey);

  $headers = [
    "Accept: application/json,text/html,*/*",
    "Content-Type: application/json; charset=UTF-8",
    "X-Public: $publicKey", // Add Public key header
    "X-Hash: $hash", // Add Hash header
  ];

  // Send PUT request
  $response = Curl::put('https://api.safeguard24.eu/' . $api_version . '/bolt/unlock', $content, $headers);
?>

  number: ELE78UT
  unlock_code: 0044161

  {
    "error": false,
    "msg": "Bolt unlock accepted",
    "status": 200,
    "_data" : {
      "unlock-id":  1397601756895433440,
      "unlock-status": "SENT"
    }
  }

  {
    "error": true,
    "msg": "Unauthorized",
    "status": 401
  }