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.

user access token postman

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

mqtt explorer

mqtt explorer2

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
A token login gets the topics of every organization in which the token’s user has organization-wide MQTT Read. In an organization where the user’s MQTT Read is restricted to specific entities, the broker grants it no topics. Such a client has to request topic-specific credentials instead.

MQTT Credentials for User Clients

Apps and web clients that act on behalf of a logged-in user connect over MQTT over WebSocket with short-lived credentials. The server issues them for exactly the topics the client asks for, as far as the user may read them. This works for users with organization-wide MQTT Read as well as for users whose MQTT Read is restricted, and it is how the BlueRange Office App connects.

Send the topic filters you want to subscribe to via HTTPS, authenticated as the user (session, access token or Basic Auth):

Request
POST /relution/api/v1/iot/mqttSubscriptionCredentials
Content-Type: application/json

{
  "protocol": "MQTT_OVER_WEBSOCKET",
  "subscriptions": [
    "rltn-iot/{organizationUuid}/{siteUuid}/{deviceUuid}/sensor/CO2/0/sensorData",
    "rltn-iot/{organizationUuid}/{siteUuid}/{deviceUuid}/sensor/WINDOW_CONTACT/0/sensorData"
  ]
}

protocol is optional and defaults to MQTT_OVER_WEBSOCKET; native MQTT is reserved for enrolled devices. subscriptions holds 1 to 50 MQTT topic filters of at most 512 bytes each.

Response
{
  "serverURIs": ["wss://iot.example.com/mqtt"],
  "clientId": "Subscription-fe404ca0-3e51-11e8-b566-0800200c9a66-9c1f…",
  "username": "Subscription-fe404ca0-3e51-11e8-b566-0800200c9a66-9c1f…",
  "password": "4b7e…",
  "variables": { … },
  "granted": [
    "rltn-iot/{organizationUuid}/{siteUuid}/{deviceUuid}/sensor/CO2/0/sensorData"
  ],
  "denied": [
    "rltn-iot/{organizationUuid}/{siteUuid}/{deviceUuid}/sensor/WINDOW_CONTACT/0/sensorData"
  ]
}

The connection properties have the same meaning as in the response of GET /relution/api/v1/iot/mqtt. In this example the user may read CO2 but not WINDOW_CONTACT. To use the credentials:

  • Connect to one of the serverURIs with the returned clientId, username and password. A CONNECT with a different client id is refused.

  • The credentials are single-use: they are valid for one CONNECT within 30 seconds of being issued (the server operator can change this with mqtt.subscriptionCredentialTtl). Request new credentials before every connect and reconnect, and turn off your MQTT library’s automatic reconnect, which would retry with the used credentials.

  • Subscribe only to the filters in granted. The broker refuses the filters in denied; read their values via the REST API instead, or leave them out.

  • The granted topics are fixed for the lifetime of the connection. Permission changes apply at the next connect.

  • A session holds at most three unused credentials. A further request discards the oldest one.

Status Cause

400

No topic filters, more than 50, or a filter that is not a valid MQTT topic filter or longer than 512 bytes.

403

Not HTTPS, the user has no MQTT Read, native MQTT was requested, or none of the filters is granted.

501

MQTT is not configured on the server, or the broker does not use the BlueRange authentication plugin.

Which Topic Filters Are Granted

The filters are evaluated per organization; the organization in the topic must be one of the user’s organizations.

With organization-wide MQTT Read (or MQTT Write)

Every filter below br/, rltn-iot/, rltn-mdm/ and rltn-mqtt/ of the organization is granted, including #.

With a restricted MQTT Read

Only the following sensor data topics can be granted:

Topic filter Granted if

rltn-iot/{org}/{siteUuid}/{deviceUuid}/sensor/{type}/{index}/sensorData

the grant covers the device.

rltn-iot/{org}/{siteUuid}/+/sensor/{type}/{index}/sensorData

the network is granted With descendant elements.

br/{org}/{buildingUuid}/{floorUuid}/{roomUuid}/sensorData/{type}

the room is granted With descendant elements, directly or through its floor or building.

br/{org}/{buildingUuid}/{floorUuid}/+/sensorData/{type}
br/{org}/{buildingUuid}/{floorUuid}//sensorData/{type} (devices directly on the floor)

the floor is granted With descendant elements, directly or through its building.

In addition, the user must be allowed to read the sensor {type} (see Which Permission Reads Which Sensor Type); + as type requires Sensor Data (Read). {index} is a number or +. Everything else is denied, including #, a + for the network, building or floor, and all other topics.

Organization-wide MQTT Credentials

GET /relution/api/v1/iot/mqtt returns connection parameters whose broker access covers every organization in which the user has organization-wide MQTT Read. Devices, Gateways and API-token clients use this endpoint. For user clients it is deprecated in favor of topic-specific credentials.

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

For a user whose MQTT Read is restricted in the current organization, the endpoint answers 403 with the message MQTT_READ is entity-scoped, use POST api/v1/iot/mqttSubscriptionCredentials.

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