Authentication

Authentication is performed using HMAC-SHA256 hashes. This method uses public and private API keys (generated by EdGate), a current UNIX timestamp and the set of passed in parameters to generate a hash that is passed in the headers of the request.  This hash is used to authenticate the request and to verify the identity of the calling party.

Components

Name Value Description
publicKey Public API Key Public key generated by EdGate that is passed with every request to identify the client
privateKey Private API Key Private key generated by EdGate that is used to create the HMAC hash passed with the request. Also used by EdGate to authenticate the request.
timestamp UNIX timestamp Timestamp that request was made, used to check whether request has expired.  Requests are valid for up to 15 minutes.

Summary of steps

  1. Generate a current UNIX timestamp

  2. Combine the publicKey and timestamp with any other request parameters

  3. Generate HMAC hash using the privateKey and parameter string

  4. Set an “X-Hash” request header using the value of the generated hash

  5. Send request

  6. Parse response

Example request (in PHP)

<?php

//public and private keys

$publicKey = 'example';

$privateKey = '6a3c8fb1062285ee69d111ca77e6f72957e55dfa0e3ac277a5a5ef82c7ba6208';

//get current UNIX timestamp

$stamp = time();

//build parameter string, adding publicKey and timestamp

$parameters = “publicKey=”.$publicKey.”&timestamp=”.$stamp.”&param1=value1”;

//generate HMAC hash of parameters

$hash = hash_hmac('sha256', $parameters, $privateKey);

//set header array for CURL, including X-Hash header

$headers = array(

    'X-Hash: '.$hash

);

//this example is a GET request, if POST/PUT/DELETE, parameters string would be set as the //request body

//set CURL options

$ch = curl_init('http://api.edgate.com/profile/?'.$parameters);

curl_setopt($ch,CURLOPT_HTTPHEADER,$headers);

curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);

//make request

$result = curl_exec($ch);

//close connection

curl_close($ch);

//decode response

$response = json_decode($result);

?>