Skip to main content

Rest API service

Essential information

It is essential that you have a working and active account and have full access to it. You need to have one to be able to access the API key or for the creation of the authentication token. We kindly request that you always check the network tab during the development of your page in case you have created an accidental loop and are spamming Http-Calls onto our server by chance.

First steps

Before being able to start working with our Api there are a couple of things one has to do:
You can authorize yourself in two different ways. You can either request a Bearer Token from our backend and append it to your Http-Call. Or you can choose to use our Diffie-Hellman key exchange procedure. In this process instead of having first to transfer the Secret Key you can generate a your AppId with its corresponding API-Key, which is only seeable for you. The secret key procedure is more advisable for static calls, that don't change or only marginally since the creation of the needed header-attribute can be a decent amount of extra work.
You can generate the Id-Key pair in the API-Keys page of your account in the Cockpit.
With these couple of first steps, you should be able to make full use of our Api und all its usage behind it.

Pathing to the Api-key creation page

Pathing to the Api-key creation page

Display of the Api-key-creation page

Display of the Api-key-creation page

Api Authentication - Bearer Token

To make our backend more secure and shield ourselves from the outside world, we work with an authentication system. This authentication system is based upon a bearer token, which needs to be sent in the header of every API interaction. Without the bearer token in the header, you will receive a CORS-Error or a 401 Error. 
In case you have added a token to your header and still get one of the mentioned errors above; create a new token and append it to the header and try again. It might have happened that the one you were using was cleared or ran out in its lifetime. 

The authentication code should be in a section of a website which is hidden for security reasons. For example, in a React project which is extended with a Controller, place the bearer-token request within that controller and access is it via a http-Call.
To be able to make a successful call you need to have the given settings as shown in the example code next the text. As for the Username and password you need to exchange them for your credentials or of the credentials of the user accessing the Api-calls. The Code-segment has hard-coded but in case you wanted to extend your controller with an expected body and fill the username and password with those information you are always allowed to do that.
On the frontend side of your webpage you can append the bearer token to all http-call-headers on the “callback” of the “getToken” http-call.



It is important that you make use of a proxy server or anykind of middleman for the API calls as they need to include the bearer token to be executed. Therefore we advise to use the c# backend as a proxy or use the Node.js way as it is in the link below. The exmaples within the React.js are not a safe way to do it but are easier to understand that way.

In case you don't want to use a proxy server, you can always create a second account and use those credentials for the token-generation. This account can be given the rights to only have read and write access to the needed parts. With this method, even a power-user with malicous intent can't create any harm with the bearer token.

In case you wanted to create the token with Node.js or use Node.js as a proxy, we have also prepared an example for that. It is to be found under the following link: Node.js example

Api Authentication - API-key

To make sure that you deliver the correct information within the header of the API-call, we have broken down what needs to be contained within the headers.

The header is expected to have 2 attributes, one is a timestamp the other is a string which gets filled by with determined information.
The authorization-timestamp is very self-explaining, this attribute gets filled with the timestamp when the http-call gets executed, meanwhile the authorization attribute is a bit more complex.

The header-attribute is expected to have a this structure:
“TicketinoAPI {appId}:{base64Signature}:{nonce}”

The signature is expected to be given in its encoded state in base64.
The signature itself is not a predetermined signature but one which needs to get coded by hand. We would advise you to create the signature in the C# part of your project. Within the C# code we are using the string.Format() method, there we fill the string with the expected layout as well as hand over the needed variables to be filled in.
For the string format we have defined "{0}\n{1}\n{2}\n{3}\n{4}\n{5}" and after said attribute we fill it with the needed variables.
The expected variables are as follow; the order of attributes needs to be the same:

  1. AppId
  2. RequestHttpMethod
  3. RequestUri (including the parameters, excluding baseUrl, all in small letters)
  4. RequestTimeStamp
  5. Nonce

After having created the string, we expect you to encode the newly crated string into a UTF-8-Bytes, we also do the same with the API-key, the one that is connected to your AppId. Beware this is the secret key for the hashing. Therefore, take care in how and where you store the key in case this key gets out or gets used by someone else besides you immediately delete your corresponding AppId and API-key in the cockpit.
After having encoded your signature and secret-key we create a “HMACSHA256” object with secret-key-bytes as an attribute in the constructor. Afterwards we can hash our signature with the newly created HASH. After that we convert the newly hashed signature to a base64String, and this is our final signature string which gets appended in the header attribute.

The route of the controller needs to be same excluding the domain, so that the requestURI gives back the same answer for you end as well as our end. In case you don't want to do that you can always change the controller to expect a string from the frontend where it hands over the requestURI in the needed format.

Example of the expected header request

Example of the expected header request

All the displayed information has been put together by the Developmentteam. This page is here to help 3rd party users to impement our system correctly.