REST API

EMS Online makes use of a REST API with a JSON body.

The API URL to be used is: api.online.emspay.eu

HTTPS

The API is only accessible using HTTPS and is secured using TLS (SSL). We support TLS 1.2 and newer. Older versions of SSL and TLS are vulnerable and not supported.

Authentication

An API client must authenticate itself for every request to the API. The client can do this by using HTTP Basic Authentication. The username is the API key as generated by EMS Online, the password remains empty.

An example of an Authorization header:

Authorization: Basic aHVudGVyMjo=

The value after “Basic” can be obtained by encoding the API key (followed by a colon) using the Base64 algorithm. The API key hunter2 followed by : will result in the string aHVudGVyMjo=.

Most HTTP clients support Basic Authentication out of the box and do not require manual construction of the Authorization header.

HTTP Status codes

The api can respond with the following http status codes.

Code Definition Example
200 Ok
201 Created
400 Bad request Used when the request is invalid
401 Unauthorized
403 Forbidden Used when the request is not allowed
404 Not found Used when the resource could not be found
500 Internal server error Indicates that there is a problem why we could not serve the request
502 Bad gateway Can be triggered when the unreachable
503 Service Unavailable Can be triggered when the system is down
504 Gateway Timeout Can be triggered when the system does not respond in time

Test api key

Test credentials can be easily obtained by creating an account. After creation you can login and view your api key under Settings > API Keys.