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.

Swagger documentation

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/.

Authentication

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 /api/v1/auth/login endpoint. 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.

JWT Payload

The JWT payload currently contains two pieces of information:

  • userId of the logged in user.

  • email (username) of the logged in user.

JWT Expiration

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.

Using Swagger with authorization

To use Swagger with protected endpoints you must first login, and provide either a API key or JWT to Swagger. This is done by pressing the “Authorize” button near the top right.

To test your login with JWT, the /api/v1/auth/profile endpoint can be called, it will return the contents of the JWT payload.

To test your login with an API-key, the GET /api/v1/application endpoint can be called. It will return all applications that this API-key gave you permission to.

Authorization (Permissions)

Permissions are given on specific applications to users and API keys through UserGroups. A UserGroup can have multiple permissions.

There are five levels of permissions in OS2IoT:

  • Global Admin

  • Can do everything for all organizations and applications

  • Application Admin

  • Is scoped to a single organization and zero or more applications

  • Can access and modify applications and Sigfox devices within the user group in that organization

  • Gateway Admin

  • Is scoped to a single organization

  • Can access and modify gateways within that organization

  • User Admin

  • Is scoped to a single organization

  • Can access and modify users and permissions within that organization

  • Read

  • Is scoped to a single organization and zero or more applications

  • Can read (view) entities within certain applications within an organization

Each of the admin permissions is part of a hierarchy with the read permission. If you have an Admin permission within an organization, with zero or more applications, you have an implicit read permission within that scope. For instance, if a user has Application Admin within an Organization, then that user also has Read permission within it.

Global Admin is at the top of the hierarchy and can thus do what any of the other permissions provide access to.

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.

Configuration

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.

Usage

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 00000000-abcd-ef00-0000-012345678901

  • This API key is tied to a user group with Read priviliges to an organization and all its applications

  • There exists a GET endpoint for fetching applications. The route ends with /application

  • The Base URL for the OS2IOT Backend is known, e.g. https://os2iot-backend.SERVERNAME.EXAMPLE/api/v1/chirpstack/

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 HTTP header “x-api-key”.

Usage in Postman

Below, a screenshot is shown of how this can be done in Postman.

api-key-usage

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.

Usage in Python

A simple example of making the API call in Python

import requests
url = "https://os2iot-backend.SERVERNAME.EXAMPLE/api/v1/application?limit=2&offset=0"
headers = {
  'x-api-key': '00000000-abcd-ef00-0000-012345678901'
}
response = requests.request("GET", url, headers=headers)
print(response.text)

Limitations

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 /api-key-info/organization.

Currently, there’s no expiration date on an API key. It will not expire unless an administrator revokes it on the key management page.