Authentication

The REST API authenticates to the helpdesk using an API key and a secret - using the API key your connecting application has access to all of your helpdesk's data. This means that the REST API has no concept of staff, team or department permissions.

Every request you make to the API must carry with it an API key, a randomly generated salt string, and a signature.

Component Where to find it Information
API key In the administrator control panel (under REST API).  
Salt Randomly generated for every request you make to the API.  
Signature Computed by hashing the salt and the secret key for every request you make to the API. The signature is a SHA256 hash of the salt with the secret key used as the hashing key.
Secret key In the administrator control panel (under REST API). The secret key is never sent in your API requests. It is only used as the key to compute the signature.

Generating the Signature

To generate a request signature:

  1. Generate a random string to create a salt (in PHP, you would use mt_rand() to do this)
  2. Generate the signature by hashing the salt using SHA256 with the secret key as the key (in PHP, you would use hash_hmac() to do this)
  3. base64 encode the signature (in PHP, you would use base64_encode() to do this)
  4. URLUniform Resource Locator is the address of a web page on the world wide web. encode the output (in PHP, you would use urlencode() to do this)

It is recommended that the value of salt be randomized for every request to ensure secure authentication.

Testing the API

We recommend using cURL. ReqBin is an easy to use online cURL client. Your helpdesk comes with an API Test Controller, which you can use to quickly test your REST API implementation.