A NEW ERA OF INTELLIGENT QUANTITATIVE ECOMMERCE - THAT WORKS FOR YOU ECOMMERCE - THAT WORKS FOR YOU
Knowledge Base
+
Admin Messages (1)
+
Common Tasks (1)
+
Insights (1)
+
Interventions (1)
+
Languages (1)
+
Questions & Answers (1)
+
Reviews (1)
+
Site Scripts (1)
+
Web Services (1)

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
FIELD REQUIRED? TYPE NOTES
Signature Yes String The Signature that you have just created. This is the main way that the API will verify that a request is coming from an allowed source.
Timestamp Yes String
(but cast into a DateTime object in the format yyyy-MM-dd HH:mm:ss)
This must be a UTC DateTime that is within two minutes of the server's current time or the request will be considered too old and will not be processed (in this case you will need to create a new Signature). It must also be the same DateTime that was used when you generated the Signature.
APIKey Yes String
(32 characters)
As described in API - API Keys.

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:

    {
    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
  3. Store the response as follows:

    var responseFull = $.post(DomainName 'api/v1/Authentication/Authenticate', authenticate)

  4. Parse the response to a JSON object:

    var responseProperties = JSON.parse(responseFull.responseText);

    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 (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 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:

{
AuthenticationToken: "YmWaLx5DyTrZbKrxq2cfhKGw3/1XC8q6",
TimeStamp: "2018-10-02 11:53:39",
Signature: "107240227137141176892730201158482262021231351582078422"
}

You then post this as follows:

var responseFull = $.post(DomainName 'api/v1/Authentication/CheckTokenTime', checkTokenTime)

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.

NOTE: As described above, you can use an AuthenticationToken for up to five minutes to call any method (apart from Authenticate itself). After five minutes you will need to generate a new AuthenticationToken and so you must first create a new Signature and repeat the Authentication process. You will therefore need to use the APIKey and Timestamp fields again, however the Timestamp is valid only if it is within two minutes of the current time – therefore you would need to create a new Signature after two minutes had passed.




Copyright © 2018 IRP Commerce. Use of this website constitutes acceptance of the IRP World Terms of Use, IRP Privacy Policy and IRP Cookie Policy
IRP Commerce is a Trading Name of Export Technologies Limited, a Deloitte Fast 50 Company six times: 2010, 2011, 2012, 2013, 2014 & 2018   Deloitte.