To gain access to the API you need to get an API ticket from the Meridix Studio installation you are going to target. The API ticket needs to be granted access to the API interfaces you wish to use. Some of the APIs have additional authorization based on the type of API ticket you are using e.g. the Units API can only be used to access units for the specific customer that the API ticket is created on.

Option 1 - JWT - JSON Web Token support (recommended)

Meridix support JWT and a token can be created at the API endpoint located at /api/auth/jwt by sending the the token and secret as a payload se below with the Content-Type header set to application/json.

Request payload

{
  "token": "TICKET-TOKEN-VALUE-HERE",
  "secret": "TICKET-SECRET-VALUE-HERE"
}

Result that contains the JWT that should be used in upcoming requests against the API.

{
    "jwtToken": "USE-THIS-VALUE",
    "createdAt": "2018-12-07T13:55:08.2663663Z",
    "expiresAt": "2018-12-08T23:15:08.2433638Z",
    "revocable": true,
    "apiTicketType": "system_ticket",
    "apiTicketOwner": "sys",
    "informationMessage": "",
    "meridixVersion": "x.x.x.x"
}

Use the value in the property jwtToken in the Bearer header e.g. Authorization: Bearer JWT-VALUE-HERE

Read more about JWT at https://jwt.io/introduction/

Option 2 - Creating a signed request

Meridix has a tool that can help you create the signed request:
http://lab.meridix.se/meridixwebapisign
The tool takes a URL, Token, Secret, Nonce and Timestamp and displays all the intermediate parts in the correct format (see steps below).

There are also easy implementation examples in several different languages available.

• Example in C#
• Example in F#
• Example in Node.js
• Example in PHP
• Example in Java
• Example in Ruby
• Example in Python 3.x

A Meridix Studio API ticket contains a Token and a Secret that is used to create a signature that need to be sent to the API with each request. The token will be sent in clear text to the server along with a random nonce value and a timestamp. A signature value needs to be created by the client. This section will describe how you create a valid signature for a specific query.

Every request sent to the API need to include the following query string parameters with the values set according to the current UTC time of the request and the API ticket used.

• auth_token
• auth_nonce
• auth_timestamp
• auth_signature

Creating a authorization signature

The following steps needs to be done in order to create a valid signature. A valid API ticket on the target server is needed as well as valid access rights to the target API. See the different API descriptions for information about the access rights needed on the ticket.

1. If we are going to authenticate the following URL: http://site.meridix.se/api/customer/listcustomers the following steps needs to be taken. Any non auth_ querystring should also be included in steps below before signing the request.
   
   
2. Create a random nonce value. This value can be any string or integer value. Ex: 84c2e241
   This value needs to be uniqe every on request.
    
3. Create a timestamp value. This value should be the current UTC time. The format should be [year-4][month-2][day-2][hour-2][minute-2][second-2] e.g. 2012-11-24 11:26:46 (UTC) should be formatted as 20121124112646.
   A timestamp value is valid for 10 minutes i.e. you cannot execute an API function with a timestamp that is older than 10 minutes.
   
   
4. Set each of the predefined parameters as well as any specific input parameters and order them in ascending order based on both the key and the value.
   auth_nonce=84c2e241
   auth_timestamp=20121124112646
   auth_token= 35f94ba7c9bd4b8887b66baa8b566c28
    
5. Concatenate all parameters (incl. any non auth_ aswell) with a & delimiter and a = between the name and value. The parameter values should not be URL encoded.
   auth_nonce=84c2e241&auth_timestamp=20121124112646&auth_token=35f94ba7c9bd4b8887b66baa8b566c28
    
6. Url encode the concatenated parameter string (see the section URL Encoding for valid encoding settings)
   auth_nonce%3D182b8848%26auth_timestamp%3D20121124112646%26auth_token%3D35f94ba7c9bd4b8887b66baa8b566c28
    
7. Url encode the url without the query part.
   http%3A%2F%2Fsite.meridix.se%2Fapi%2Fcustomer%2Flistcustomers
    
8. Concatenate the current requests HTTP verb (e.g. GET) in upper case with the encoded url and the encoded parameters and add the secret (2c9e39f72f434a8) at the end. Separate all parts with & characters.
   
   GET&http%3A%2F%2Fsite.meridix.se%2Fapi%2Fcustomer%2Flistcustomers&auth_nonce%3D182b8848%26auth_timestamp%3D20121124112646%26auth_token%3D35f94ba7c9bd4b8887b66baa8b566c28&2c9e39f72f434a8
   
   Get the UTF8 byte representation of the concatenated string above and create an SHA512 hash signature in hex format (lowercase) based on the string. The string above would result in the following signature 8daa7e4bd69baebbcdd1b3fbae9489ff
    
9. Use the created signature as the value for the auth_signature parameter. And append it the the current query string that should be sent to the server
   
   
10. http://site.meridix.se/api/customer/listcustomers?auth_nonce=182b8848&auth_timestamp=20121124112646&auth_token=35f94ba7c9bd4b8887b66baa8b566c28&auth_signature=8daa7e4bd69baebbcdd1b3fbae9489ff This query is now signed and ready to be sent to the server

URL Encoding

The URL encoding is based on the encoding scheme implemented by the .NET Uri.EscapeDataString method. See for more information about valid URL encodings http://msdn.microsoft.com/en-us/library/system.uri.escapedatastring.aspx

From MSDN: By default, the EscapeDataString method converts all characters except for RFC 2396 unreserved characters to their hexadecimal representation