Authentication

Introduction

The Unleashed API is linked to the Unleashed web application at https://go.unleashedsoftware.com/v2.

1. You need to create an account before you can use the API.
2. Trial accounts can access the API.
3. To use the API you need an API id and private key. These can be found on the API access page inside the Unleashed application. Each company that you have access to in Unleashed will have a different API id and private key.

Note: Your API id and key are equivalent to a login and password. They must be kept secret and not shared in any way.

A sample API client provided demonstrates how to use the API. The sample application requires .NET framework version 4 and ASP.NET MVC version 2 or above.

Download the C# sample API client here.

C# sample code

PHP sample code

Each request to the API must include these four values sent as HTTP headers:

• Content-Type - This must be either application/xml or application/json.
• Accept - This must be either application/xml or application/json.
• api-auth-id - You must send your API id in this header.
• api-auth-signature - You must send the method signature in this header.
• client-type - You must send your client-type in this header to enable tracking. The value must follow the convention partner_name/app_name or Accountname/app_name. e.g. acme/acmeEDI.
  • The partner_name  is the name of the company name that has built your integration.
  • The Accountname should be used if this is internally built and should be your Unleashed Account Name (e.g. ABC Company Ltd).
  • The app_name describes what you are connecting to or the purpose of the API request (e.g. SyncSalesOrders).

Note: Whilst client-type is not explicitly enforced by the system, we strongly encourage you to send client-type in this header for API tracking and usage purposes.

The method signature must be generated by taking the query string, and creating a HMAC-SHA256 signature using your API key as the secret key.

Only the query parameters portion of the URL is used in calculating the signature, e.g. for the request / Customers?customerCode=ACME use the string customerCode=ACME when generating the signature. Do not include the endpoint name in the method signature.

Do not include the query indicator ? in the method signature.

If you generate the signature incorrectly you will not be able to access the API, instead you will only receive a “403 Forbidden” response.

Note: The query string can also be empty, e.g. for the request /Customers, in which case you must provide a signature created by calling GetSignature(empty string, your key).

private static string GetSignature(string args, string privatekey) {
    var encoding = new System.Text.UTF8Encoding();
    byte[ ] key = encoding.GetBytes(privatekey);
    var myhmacsha256 = new HMACSHA256(key);
    byte[ ] hashValue = myhmacsha256.ComputeHash(encoding.GetBytes(args)); 
    string hmac64 = Convert.ToBase64String(hashValue); 
    myhmacsha256.Clear();
    return hmac64; 
}