Client API authorization

The Client API has 2 kinds of users:

• Anonymous users
• Registered users

Anonymous users are users which we don't know anything about. These can be users that are not logged in on your web application. These users are communicating, with the Client API, without the Authorization header present (or empty). Once these users close their chat and come back later to start again, they won't be able to see their messages because Parley doesn't know who they are.

Registered users are users on which we have some specific information. Let's say a user logs in on your web application. This user has some sort of unique 'identification' in your system. You can send this identification to the Client API and Parley will create it's own user with this "external" identification. This identification is put in the Authorization header, it is the customerId parameter in the examples below. Whenever a user closes their webbrowser and comes back later, it can re-use this authorization string to get his message history back (or generate a new authorization string if the previous one is expired)

Generating the Authorization string

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

• customerId: The unique customer identification
• sharedSecret: A secret which is shared with You and Parley, which is used to verify this authorization string
• secret: A secret specific for this user used to encrypt his messages (Parley has no way of reading this secret because it is hashed together with the shared secret)
• validUntill A unix timestamp which will tell Parley when this authorization should be considered invalid

When you have all this information you can start generating the authorization string by using one of the example codes below.

Important

• It is important you generate the authHeader in a safe and secure location (not on a client device).
• The customerId has a limit of 100 characters, anything above will result in a "api_key_not_valid" error
• verifyHash must be a hexadecimal string (PHP's hash_hmac does this by default, but other languages don't)

PHP

<?php

	function parleyAuthentication($customerId, $sharedSecret, $validUntill, $secret)
	{
		$customerAuthenticationKey = hash_hmac(
			'sha512',
			$customerId,
			$secret
		);

		$verifyHash = hash_hmac(
			'sha512',
			$customerId . $customerAuthenticationKey . $validUntill,
			$sharedSecret
		);

		$authentication = base64_encode($customerId . "|" . $customerAuthenticationKey . "|" . $validUntill . "|" . $verifyHash);

		return $authentication;
	}

	$customerId = ""; //Unique customer id (can be anything, ex: 12345 or ABCD)
	$sharedSecret = ""; //Received from Parley
	$secret = ""; //Create your own
	$validUntill = ""; //Unix timestamp

echo parleyAuthentication($customerId, $sharedSecret, $validUntill, $secret);

Node.js

/*
* Do not attempt to run this in a client side javascript environment, that will
* defeat the purpose of the authorization header. Because that will enable any
* user to create authorization headers to impersonate someone else.
*/

var crypto = require("crypto");

function parleyAuthentication(customerId, validUntil, sharedSecret, secret) {
	const keyHmac = crypto.createHmac("sha512", secret);
	keyHmac.update(customerId);
	const customerEncryptionHash = keyHmac.digest("hex");

	const verifyHmac = crypto.createHmac("sha512", sharedSecret);
	verifyHmac.update(`${customerId}${customerEncryptionHash}${validUntil}`);
	const verifyHash = verifyHmac.digest("hex");

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

	return authentication;
}

const sharedSecret = ""; //Received from Parley
const secret = ""; //Generate your own
const validUntil = ""; //Unix timestamp in seconds
const customerId = ""; //Unique customer id (can be anything, e.g. 12345, my@email.com, 1000AA-11)

const userAuthentication = parleyAuthentication(
	customerId,
	validUntil,
	sharedSecret,
	secret
);
console.log(userAuthentication);