API - Authenticate Method

You use the Authenticate method with all APIs to gain an AuthenticationToken which you then use to call other API methods.

You combine the Signature with the APIKey and the Timestamp in the Authenticate method in order to gain an AuthenticationToken. You will then use the AuthenticationToken in place of the APIKey for all subsequent method calls (other than to the Authenticate method itself) – however see the Note on expiry times below. The Authenticate object must contain the following fields:

Table 1. Authenticate Method Allowed Values

Proceed as follows:

1. Construct the Authenticate object containing the fields described above. Here is an example authenticate object containing the Signature, APIKey and Timestamp:

   var authenticate = {
APIKey: "WJCwQJbKcmB3QbhHxdfH5ET2yf5KsaBN",
TimeStamp: "2018-10-01 15:10:54",
Signature: "1615814919621920710221623417615224420914820125013020012150"
};

2. Post the Authenticate object to your website's base URL plus /api/v1/Authentication/Authenticate (in the example below, replace https://www.yourdomainname.com with the domain name where your API is located):

   $.post('https://www.yourdomainname.com/api/v1/Authentication/Authenticate',
authenticate,
function(data){ // 'success' function
....
})

3. Within the success function above, you can get access to the returned JSON object as follows:

   var responseObject = JSON.parse(data);

   This allows you to access the various properties of the response from the API:
   • Success: This indicates whether or not the requested method was executed and can have one of the following values:
     • True
     • False
     • Warning (this indicates that whilst the method has succeeded, it is accompanied by a warning message)
   • Messages: If Success is 'False' then Messages will be an array of error message detailing what prevented the method from executing successfully. Otherwise this will be an empty array.
   • Signature: The Signature will be the same as the Signature that was passed in with the request (but does not include the API Key in the response).
   • Timestamp: This is used for verification purposes and is generated at the time of the response.
   • AuthenticationToken: This token must be included in every object that you post to the API except for ones posted to Authenticate. They are tied to the API Key that was granted them and, as such, they should be passed in with a Signature that was generated using the API Key.
   Here is an example of the return object in the event of an error when trying to authenticate:

   {
"Messages":[{"Code":2005,"Message":"Value Is Shorter Than The Minimum Length.(Parameter=APIKey)"}],
"Success":false,
"Signature":null,
"TimeStamp":"2018-10-16 14:27:31.5523349Z"
}

   And here is an example of the return object in the event of a success when trying to authenticate:

   {
"AuthenticationToken":"poIx6a6wYCQJPdDcBbUs2cApYjU0aQFq",
"Messages":[],
"Success":true,
"Signature":"80dbc28a0b835306471d06b20f2165155e68d9c3",
"TimeStamp":"2018-10-16 14:24:46.8838787Z"
}

Note on expiry times

The AuthenticationToken will expire five minutes after it was created, therefore you will need to authenticate again and receive a fresh AuthenticationToken for further posts to the API.

There is a method (https://www.yourdomainname.com/api/v1/Authentication/CheckTokenTime) in the Authentication API to check how much time an AuthenticationToken will be valid for. This is useful if you're using the same token to make multiple calls as you can check if a new one is needed before sending a request, rather than just sending one and checking if it failed. The https://www.yourdomainname.com/api/v1/Authentication/CheckTokenTime method does not require any extra values beyond the ones always required, the AuthenticationToken you wish to check, the current UTC DateTime and the Signature constructed in the same way as before.

The object you send should resemble this:

You then post this as follows (in the example below, replace https://www.yourdomainname.com with the domain name where your API is located)

The object returned will contain one extra field from the default fields: MinutesRemaining. This will show you how long is left on this token in MM:SS format.