Authentication

Every request to our API needs to be authenticated and signed with a Hashed Message Authentication Code (HMAC) Signature.

API Keys

First of all you need to generate your API Keys in the Seller Office. They consist on a Client Key and Client Secret. Please, write them down once they are generated as the Client Secret can’t be seen afterwards.

Headers

Each request must contain the following four headers:

Header Explanation
Accept Accept header set to application/json.
X-Client-Id This is the value of the Client Key.
X-Timestamp Set X-Timestamp with the current Unix Timestamp in seconds and must be current at the time the request is made. There is a 10-minute window around the current time to account for clock skew. In other words, timestamp can be up to 5 minutes earlier or 5 minutes later than the current server time. If the timestamp is more than 5 minutes different from the current server time when the request is received, the request will be rejected.
X-Signature It contains an HMAC signature of the request. The HMAC is specific to each request, so it must be regenerated for each request.

How to sign a request?

Each request must be signed by a SHA-256 HMAC in base64 encoding. This HMAC is generated by concatenating the request information together, separated by newline characters, and generating a SHA-256 HMAC from the resulting string and the Client Secret (Key). Here is an implementation of the HMAC generation function in PHP:

function signRequest($method, $uri, $body, $timestamp, $secretKey)
{
    $string = implode("\n", [
        $method,
        $uri,
        $body,
        $timestamp,
    ]);
 
    return hash_hmac('sha256', $string, $secretKey);
}

The required values in the signature string are:

  • $method- The HTTP method of the request, uppercased (e.g. GET, POST, PATCH, DELETE).
  • $uri - The full URI of the request, including https:// and the full domain name (e.g. https://app-seller-pim.prod.de.metro-marketplace.cloud/openapi/v1/categories).
  • $body - The body of the request. If the request doens´t have a body, you should use an empty string.
  • $timestamp - The value of the current Unix timestamp at the time of the request. This must be the same as the value of the X-Timestamp header.
  • $secretKey - Client Secret Key which you have generated in the Seller Office.

The PHP function hash_hmac() produces an HMAC using SHA-256 as the cryptographic hash function. For example, you could generate an HMAC for the following values (in PHP):

$method = "GET";
$uri = "https://service-category.sandbox.infra.metro-markets.cloud/public/api/v1/DE/categories";
$body = "";
$timestamp = 1612137600;
$secretKey = "856216c8abc2b154645613f456123aab";

The X-Signature generated by these values is 8844a35f5d2a4f57acbddf12ae3ed25973d73c2d2ec1d93c30a4fe1baddf569f

Example of how the headers would look like in the HTTP Request above:

GET  /public/api/v1/DE/categories HTTP/1.1
Host: service-category.sandbox.infra.metro-markets.cloud
Accept: application/json
X-Client-Id: bc456123-4561-1d56-4def-456b30abc123
X-Timestamp: 1612137600
X-Signature: 8844a35f5d2a4f57acbddf12ae3ed25973d73c2d2ec1d93c30a4fe1baddf569f

Here you can see a full example using PHP:

<?php
function signRequest($method, $uri, $body, $timestamp, $secretKey)
{
    $hash = implode("\n", [$method, $uri, $body, $timestamp]);
    return hash_hmac('sha256', $hash, $secretKey);
}
$url = "https://service-category.sandbox.infra.metro-markets.cloud/public/api/v1/DE/categories";
$curl = curl_init($url);
$method = "GET";
$clientKey = "";
$clientSecret = "";
$unixTime = time();
$signature = signRequest($method, $url, "", $unixTime, $clientSecret);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    "X-Client-Id: $clientKey",
    "X-Timestamp: $unixTime",
    "X-Signature: $signature",
    "Accept: application/json"
]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
curl_close($curl);
$json = json_decode($response, true);
print_r($json);

You can find an example with Javascript in the Postman section.