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.
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.
|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.
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
Using the MQTT Token
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:
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
user name and
client identifier use the same value:
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.
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.
/relution/api/v1/iot/mqttusing HTTPS with a valid user session or Basic Auth.
Use the provided credentials and server data to establish the MQTT connection.