Service API authorization

The Service API is accessed by what we call Services.

A Service is a platform which can execute different actions on Users which have been created through the Client API.

A Service needs an Authorization string to access any of the endpoints in the Service API. This string is put in the Authorization header of each request you send to the API.

Generating the Authorization string

To generate the Authorization string, you'll need some information:

• serviceIdentification: This is the unique Service identification we create for you.
• accountIdentification: This is the unique identification of the account you want to talk to.
• validUntil: This is a unix timestamp until which this authorization string is valid.
  Once this time passes you will receive a 401 error api_key_not_valid. (this error is also shown when
  your authorization string is invalid in general)
• sharedServiceAccountSecret: This is a secret string which is shared between you and the API. It is used to sign a hash which we will try to recreate and match against the one you provided (the verifyHash).

warning

verifyHash must be a hexadecimal string
(PHP's hash_hmac does this by default, but other languages don't)

PHP

<?php

function parleyAuthentication($serviceIdentification,$accountIdentification,$validUntill,$sharedServiceAccountSecret)
{
	$verifyHash = hash_hmac("sha512", $serviceIdentification.$accountIdentification.$validUntill, $sharedServiceAccountSecret);
	$authentication = base64_encode("$serviceIdentification|$accountIdentification|$validUntill|$verifyHash");
	return $authentication;
}

$serviceIdentification = ""; // The identifier of the service used by your account
$accountIdentification = ""; // You account identifier
$validUntill = ""; // Timestamp untill when this authorization is valid
$sharedServiceAccountSecret = ""; // The secret you want to use for this authorization

echo parleyAuthentication($serviceIdentification,$accountIdentification,$validUntill,$sharedServiceAccountSecret);

Node.js

var crypto = require("crypto");

function parleyAuthentication(serviceIdentification, accountIdentification, validUntil, sharedServiceAccountSecret) {
  const verifyHmac = crypto.createHmac("sha512", sharedServiceAccountSecret);
  verifyHmac.update(`${serviceIdentification}${accountIdentification}${validUntil}`);
  const verifyHash = verifyHmac.digest("hex");

  const authentication = Buffer.from(
    `${serviceIdentification}|${accountIdentification}|${validUntil}|${verifyHash}`
  ).toString("base64");

  return authentication;
}

const serviceIdentification = ""; // The identifier of the service used by your account
const accountIdentification = ""; // You account identifier
const validUntil = ""; // Timestamp untill when this authorization is valid
const sharedServiceAccountSecret = ""; // The secret you want to use for this authorization

const userAuthentication = parleyAuthentication(
  serviceIdentification,
  accountIdentification,
  validUntil,
  sharedServiceAccountSecret
);
console.log(userAuthentication);