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

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:

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.