Authentication and Authorization

Authentication and authorization is based on an authorization header in combination with other request headers. A signature, part of the authorization header, has to be calculated for each request.

To be able to make the request you need the following information about your installation. Ask your contact person at Liana Technologies if you don’t have these:

• API User ID
• API Secret
• API Realm
• API Url

Required Headers

For every request to succeed we require the following headers:

Authorization

The requests are authorized with an authorization header. This header consists of 3 parts:

• Realm: The realm is a string of capital letters, defined by the domain of your LianaAutomation installation.
• User id: This is a unique ID for your API user (and only works with one installation).
• Signature: A signature that is calculated with other variables, explained below.

The parts are combined as follows:

{Realm} {User id}:{Signature}

Example of an Authorization header

Authorization: LCUI 1:d79ffb8112a62fb8af166cedfb96164ee7d2f3d6fea9669cd3b40f52ca69692f

Date

The date header must contain a computer readable timestamp format. Using ISO 8601 is recommended. The timestamp can be maximum 15 minutes old. You could for example launch multiple requests with the same timestamp for 15 minutes.

Example of a Date header:

Date: 2021-09-14T15:28:09+03:00

Content-md5

This header contains the md5 hash of the request body

Example of a Content-md5 header:

Content-md5: 344aab9758bb0d018b93739e7893fb3a

Content-Type

The content of the requests should be of type application/json

Example of the Content-Type header:

Content-Type: application/json

Signature

The authorization header signature is generated using HMAC with SHA-256 algorithm.

The key for HMAC is the REST user password and the message is constructed in the following way:

• Create a UTF-8 encoded string with UNIX style line endings (\n).
• Every item on it's own line, add to the string:
  • Request method: This is POST for all our endpoints
  • Content-md5: The value of the Content-md5 header 
  • Content-Type: The value of the Content-Type header
  • Date: The value of the date header
  • Content: The full content body of the request
  • PATH: The path part of the URI, including query parameters if any.

Code Samples

To test your connection you can use any of the following provided code samples that use our pingpong endpoint. 

PHP ⏬

Node (JavaScript) ⏬

Postman

You can also use Postman to create the authorization header.

• Create a new Collection
• Place the below script in the collection’s ‘Pre-requist Script’ tab
• Add the required variables to the collection’s ‘Variables’ tab
• Create a new POST request to the API url given to you, followed by /rest/v1/pingpong
• Use {“ping”:”pong”} as body content. Make sure the content is marked as raw of type JSON