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.
| Info |
|---|
| The latest versions of Meridix (3.9.0.5130 or later) support two types of API authentication; JWT and Request signing. The recommended approach is to use JWT if available. |
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
| Code Block | ||
|---|---|---|
| ||
{
"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.
| Code Block | ||
|---|---|---|
| ||
{
"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/
| Info |
|---|
| Note that JWT support is only available in Meridix version 3.9.0.5130 or later. For older versions use the signature based approach. |
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).
...
| Child pages (Children Display) |
|---|
...
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.
...
- 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.
...
| Note |
|---|
A signed request (Signature) can only be used one time, when it has been used it can not be executed again and in that case the server will return a 403 Forbidden HTTP response. The request must also be sent to the server within ten minutes from that the signing was been made (based on the UTC Timestamp in the request). |
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
...