MQTT user management

Tutorial for creating credentials for the MQTT API.

Overview¶

In this article, you will learn how to create login credentials for the MQTT API using the HTTP API.

Preliminaries¶

To execute the examples provided in this tutorial, the following is needed:

A valid login (username and password) to the aedifion.io platform. If you do not have a login yet, please contact us regarding a demo login. The login used in the example will not work!
A project with live data ingress.
An HTTP API client such as Curl or Postman.
Optionally, an MQTT client such as MQTT.fx to test your credentials.

Creating MQTT users¶

MQTT credentials with limited validity can be created using the POST /v2/project/{project_id}/mqttuser endpoint. This endpoint requires the following parameters

Parameter	Datatype	Type	Required	Description	Example
project_id	integer	path	yes	The numeric id of the project for which to add a new MQTT user account.	1
username	string	body (JSON)	yes	The username of the new MQTT user. If that username exists, the request is rejected.	my_mqtt_user
password	string	body (JSON)	yes	The password for the new MQTT user.	mys3cr3tp4ssw0rd
rights	string	body (JSON)	no	Grant read or write permissions to this account. Note that write permission imply read permissions. Defaults to read.	read
validity	integer	body (JSON)	no	This user account will expire after this many seconds. Maximum validity is 2 hours = 7200 seconds.	3600
description	string	body (JSON)	no	Human readable description what this account is about.	A new test account just for reading.

Example request

We create a new user my_mqtt_user with read rights.

POST /v2/project/1/mqttuser
host: https://api.aedifion.io
accept: application/json
content-type: application/json

{
  "username": "my_mqtt_user",
  "password": "mys3cr3tp4ssw0rd",
  "rights": "read",
  "validity": 3600,
  "description": "A new test account just for reading."
}

Example response

The response is a JSON-parseable object that contains the details of the created MQTT user. Please note: The request was posted at 16:23 CET with a validity of 3600 seconds, i.e., 1 hour. Thus the MQTT user will be valid until 17:23 CET, which is 16:23 UTC.

HTTP/1.1 201
content-type: application/json

{
  "operation": "create",
  "resource": {
    "description": "A new test account just for reading.",
    "id": 42,
    "topics": [
      {
        "id": 123,
        "rights": "read",
        "topic": "lbg01/mybuilding/#"
      }
    ],
    "username": "my_mqtt_user",
    "valid_until": "2019-01-18T16:23:01.707344Z"
  },
  "success": true
}

Modifying MQTT users¶

After the MQTT account expires it will be automatically removed. You can either create a new account with the same username afterwards or renew the existing account before it expires using the PUT /v2/project/{project_id}/mqttuser/{mqttuser_id} endpoint. This endpoint generally allows you to modify the MQTT user account. It accepts the following parameters:

Parameter	Datatype	Type	Required	Description	Example
project_id	integer	path	yes	The numeric id of the project for which to edit an MQTT user account.	1
mqttuser_id	integer	path	yes	The id of the existing MQTT user account to apply changes to.	42
password	string	body (JSON)	no	The changed password for the given MQTT user account.	ch4ng3dp4ssw0rd
validity	integer	body (JSON)	no	The expiry of the given MQTT user account will be extended by this many seconds into the future from the time of the update. Maximum validity is 2 hours = 7200 seconds.	7200
description	string	body (JSON)	no	The changed human readable description what this account is about.	A new test account just for reading with a new password.

Example request

With the following request, we change the description and password and extend the validity of the above created user.

PUT /v2/project/1/mqttuser/42
host: https://api.aedifion.io
accept: application/json
content-type: application/json
{
  "description": "A new test account just for reading with a new password.",
  "password": "ch4ng3dp4ssw0rd",
  "validity": 7200
}

Example response

The response is a JSON-parseable object that contains the details of the modified MQTT user. Note that the following response was given to a request that was posted roughly at 16:28h CET. A successful response looks like this:

HTTP/1.1 201
content-type: application/json

{
  "operation": "",
  "resource": {
    "description": "A new test account just for reading with a new password.",
    "id": 42,
    "topics": [
      {
        "id": 123,
        "rights": "read",
        "topic": "lbg01/mybuilding/#"
      }
    ],
    "username": "my_mqtt_user",
    "valid_until": "2019-01-18T17:28:39.392003Z"
  },
  "success": true
}

As you can see, the expiry date of the MQTT user account was extended by 7200 seconds = 2 hours from the time of the update and the description is changed. Of course, the changed password is not reported in the response for security reasons and it is only saved as a cryptographic password hash on the server.