Signing API requests

When you send HTTP requests to the Unicity API, you must sign the requests so that the API can identify who sent them. You sign requests with your signature, which is created using your public API_ID, your private API_KEY, the JSON data string and any optional request parameters.

All requests need to be signed.

Why Requests Are Signed?

The signing process helps secure requests in the following ways:

  • Verify the identity of the requester
    Signing makes sure that the request has been sent by someone with a valid access key.
  • Protect data in transit
    To prevent tampering with a request while it's in transit, the JSON data string is used to calculate the signature for the request, and the resulting signature is included as part of the request. When the API receives the request, it uses the same information to re-calculate the signature and matches it against the signature in your request. If the values don't match, the API denies the request.

Signing Requests

To sign a request, you calculate a JSON data string of the parameters you wish to send with the request. The JSON data string is then concatenated with your public API_ID and any optional request parameters, and then used with your private API_KEY to create a signed hash; this is the signature.

The concatenation of the JSON data string and API_ID must be done in alphabetical order. For example:

$data_to_be_hashed = $api_id . $data . $othervalue;

You then send the signature as a query string value, along with the API_ID and any optional request parameters, to the request endpoint. 

The signature must be created as a HMAC  using the hashing algorithm sha256.

Example

$api_id = 'XX';
$api_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

$params = [ 'email' => 'test@example.com', ];

$data = json_encode($params);

$sig = hash_hmac('sha256', $api_id . $data, $api_key);

$url = 'https://www.yoursite.com/admin/api/unicitymail/subscriptions?api_id='.$api_id.'&data='.urlencode($data).'&sig='.$sig;