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 five 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 - In order for Unleashed to track and identify your API calls, you must send a value for client-type. We recommend the following format:
  • the value should follow the convention of
    • <partner_name>/<app_name>, when your development is outsourced, OR,
    • <account_name>/<app_name>, when your development is inhouse
  • partner_name identifies the party who developed your integration
  • account_name is your Unleashed account name
  • The app_name describes the purpose of the api integration
  • examples:
    • thecodingcompany/orderautomation (outsourced development)
    • yourcompanyname/syncsalesorders (inhouse developed)
  • the client-type field contents
    • is free text (not validated against any pre-existing values)
    • should be in lowercase
    • should not contain spaces
    • should not contain special characters
    • should be as few characters as possible (ideally around 20 characters, but not prescriptive)

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; 
}