API Authentication

There are two possible ways to authenticate against the BlueRange Server. The preferred way is to use API tokens which you can create with any user. They allow you to authenticate against both the REST API and the MQTT API. The second possibility is to use BasicAuth which you can only use to authenticate against the REST API.

Token Authentication

Creating and Using an Access Token

The preferred way for accessing MQTT and REST is by using API token authentication. An API token (Access Token) grants the same rights as the user that initially created it. Typically, the token is generated for a user of the "Developer" group.

To create an API token log onto BlueRange as the user for which the token should be created and navigate to the user profile. If you need more help, see the documentation for creating an access token.

user profile jon b

Make sure to save the API token and the MQTT parameters as you will not be able to access this information afterwards.

Using the REST Token

The API token must be passed as HTTP header X-User-Access-Token. It replaces a plain Basic Authentication and avoids the need of passing a potentially changing password.

Also it is recommended passing the additional HTTP header X-Gofer-User with the UUID primary key of the user the access token belongs to. This prevents accidental execution when the token becomes invalid, but other authentication means allow request processing. An example of this is when the API token is deleted and the HTTP client passes a valid session cookie.

Example:

X-User-Access-Token: oepqwj-fjspiej-fcesjifj
X-Gofer-User: fe404ca0-3e51-11e8-b566-0800200c9a66

Please note that additional information including the current user’s UUID and organization UUID values can be obtained easily using the legacy endpoint /gofer/system/security/currentAuthorization.

Using the MQTT Token

MQTT Explorer

You can use the freely available MQTT Explorer to create a connection to the MQTT broker with the provided data. Below is an exemplary access token and the settings for MQTT explorer:

Access Token created in the BlueRange Portal

user access token add b

Table 1. Settings in MQTT Explorer

Make sure that you correctly configured all settings and that you also correctly entered the topic subscription. Then press "Connect". Subscribing to the topic of your organization will give you an overview over all sensor data that is being sent by devices in your organization. You can further filter this by only subscribing to a specific topic. Consult our MQTT API documentation for more info.

A special note, only if you are working with the AWS IoT Core MQTT Broker: You might only be able to connect using a valid client certificate. You should leave the username and password empty and instead go to > Advanced > Certificates and provide the three certificates that should have been provided to you.

Programmatically accessing the MQTT Broker

Middleware may access the BlueRange MQTT server directly. The access token value is used as password. The user name and client identifier use the same value: Token-User-UUID-Client-Instance. Here User-UUID is the UUID of the user the token belongs to and Client-Instance is an arbitrary text identifying your middleware client software. Using the token name is recommended. If your software requires multiple MQTT connections at the same time append an arbitrary suffix.

Example:

user name: Token-fe404ca0-3e51-11e8-b566-0800200c9a66-MyMiddleware
client ID: Token-fe404ca0-3e51-11e8-b566-0800200c9a66-MyMiddleware
password: oepqwj-fjspiej-fcesjifj

In addition, online portals may access MQTT over WebSocket using a client credential workflow.

Query /relution/api/v1/iot/mqtt using HTTPS with a valid user session or Basic Auth.
Use the provided credentials and server data to establish the MQTT connection.

Basic Authentication

You can also use BasicAuth to authenticate against the REST API. Below is a sample screenshot when using Postman to perform a GET request against our currentAuthorization endpoint.

basic auth