Security & Authentication

Signature Generation

Important Most Learnosity services require hashing of certain attributes to prevent tampering with the intended context. This article details this approach so you can replicate it in your code. However for ease of use we provide helper SDKs in several languages and strongly recommend their use.

The SDK is available in PHP, Java, ASP.Net, Python or Ruby. You can add one of these to your codebase and get going quickly by following the readme and examples in each SDK.

Use of the SDK is highly recommended. If for some reason you need to generate the security signature manually, the details are below.

A valid signature is required to authenticate each Data API request.

The signature is a 64 character long string, resulting from applying the SHA256 hashing algorithm to the concatenation of the following parameters in order, separated by underscores ('_'):

  1. consumer_key
  2. domain*
  3. timestamp
  4. consumer_secret
  5. JSON Object of the Request Packet
  6. action
* The domain is used to confirmed requests are coming from an allowed source. The Learnosity Data API server will check that requests come from one of the authorised domains associated with your consumer credentials.

The consumer_secret is a secret key supplied by Learnosity, known only by the client and Learnosity. The consumer_secret must not be exposed either by sending it to the browser or across the network.

The action only needs to be included if it's not a "get" action (eg set, update or delete). Otherwise its considered get by default. In this case, you do not need to include it in the preHashString generation, or in the initialisation packet.
$security = array(
    "consumer_key" => "INSERT_CONSUMER_KEY_HERE",
    "domain"       => "localhost",
    "timestamp"    => gmdate('Ymd-Hi')

$consumer_secret = 'INSERT_CONSUMER_SECRET_HERE';

To create the string, a simple concatenation needs to performed, in the order specified above, along with the json representation of the request object.

$request = array(
    'datetime' => "1970-01-01T03:25:55+00:00"

$action = 'get';

output format will be:
[consumer_key]_[domain]_[timestamp]_[consumer_secret]_[JSON Request]_[action]

$signatureArray = array_merge(array(), $security);

array_push($signatureArray, $consumer_secret);
array_push($signatureArray, json_encode($request));
array_push($signatureArray, $action);

$preHashString = implode("_", $signatureArray);

The SHA256 algorithm is then applied to the concatenated string creating the signature

Further examples, as well as examples in other languages, can be found in the source code for our Demos page.

$security['signature'] = hash('sha256', $preHashString);

$initOptions = array(
    "security" => json_encode($security),
    "request" => json_encode($request),
    "action" => $action

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, '');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $initOptions);
$curl_response = curl_exec($ch);