Mosquitto: How MQTT API authentication works

This documentation is part of the API authentication guide. View the full guide here: How to authenticate thousands of devices using an external API.

👋 Welcome to the Stackhero documentation!

Stackhero offers a ready-to-use Mosquitto MQTT cloud solution that provides a host of benefits, including:

• Unlimited message exchanges and transfers.
• Unlimited devices authentication via an external API.
• Advanced ACLs on topics, users and actions.
• Customizable domain name secured with HTTPS (for example, https://mqtt.your-company.com).
• Effortless updates with just a click.
• Optimal performance and robust security powered by a private and dedicated VM.

Save time and simplify your life: it only takes 5 minutes to try Stackhero's Mosquitto MQTT cloud hosting solution!

Using external API authentication is particularly useful when you have more than 20 IoT devices or when you need detailed topic ACL management.

When a device connects to MQTT, Mosquitto sends an HTTP POST request to your API. The request includes a JSON payload containing the device's username and password. If your API returns an HTTP status code 200, the device is authorised. Any status code other than 200 (such as 401) results in the device being denied access.

During ACL validation, four parameters are transmitted: username, clientid, topic, and acc. Your API should verify that the username is allowed to perform the operation defined by acc on the topic. The acc parameter is defined as follows:

1. read access (1)
2. write access (2)
3. read and write access (3)
4. subscribe access (4)

For example, if the user userA attempts to subscribe to the topic sensors/temperatures, your API will receive the following JSON:

{
  "username": "userA",
  "clientid": "userA",
  "topic": "sensors/temperatures",
  "acc": 4
}

When you use user authentication via an API, you can still define users manually in the Stackhero dashboard. In that case, the manually defined users will be given priority.