Internal Interface Design
This document describes the internal interface design of OS2iot.
Backend REST API
The primary way of communicating with the back end is through the RESTful API.
The documentation of the endpoints, their parameters and so forth is documented using Swagger.
You can access Swagger through the endpoint:
/api/v1/docs/ of the backend. So for the test environment,
it would be: https://test-os2iot-backend.os2iot.dk/api/v1/docs/.
The API is protected using JSON Web Token (JWT), see https://jwt.io/introduction/ for an introduction.
To get a JWT you must perform a login using username and password to the
In response to a valid login, a JWT is sent, inside a JSON object.
To call protected endpoints the
Authorization header must be set to
Bearer xxx.yyy.zzz where
xxx.yyy.zzz is a valid JWT.
The JWT payload currently contains two pieces of information:
userId of the logged in user.
email (username) of the logged in user.
The JWT is by default set to expire after nine hours. upon which it is invalid. To acquire a new one, a new login must be performed as described above.
API key access
OS2IoT supports API key authentification. This allows external clients to use the system without the need of a browser or a user.
In order to use this type of authentication, an administrator must create an API key with one or more user groups. This can be done on the portal through the API key management pages. It can be accessed through the menu.
With an API key, you can fetch and manage data in your OS2IoT system just as well as if you were a user on the browser. What you can access and manage is limited by the user group (-s) tied to the API key.
With that in mind, let’s dive into using an API key. Let’s make a few assumptions:
We have an API key with the value
This API key is tied to a user group with Read priviliges to an organization and all its applications
There exists a
GETendpoint for fetching applications. The route ends with
There’s a broad variety of applications, terminals etc. which can perform HTTP requests. To authenticate this request with the API key, you must provide it as the header “x-api-key”. Below, a screenshot is shown of how this is done in Postman.
The bottom half of the screenshot is the response. The request was limited to 2 applications using the
limit query parameter.
As seen, the backend responded with 2 (collapsed) applications.
While most of the system is accessible using API key authentication, there are some security limitations, however:
You cannot manage your API key or someone else’s
You cannot manage users nor user groups
You cannot manage organizations
You can use an API key to request information necessary for using OS2IoT by using endpoints starting with
/api-key-info. They require API key authentication.
For instance, to fetch the organization tied to your API key, you can make a
GET request to the route which ends with
Currently, there’s no expiration date on an API key. It will not expire unless an administrator revokes it on the key management page.