Mosquitto: How MQTT API authentication works

This documentation is part of the API Authentication guide. You can view the complete guide here: How to authenticate thousands of devices using an external API.

👋 Welcome to the Stackhero documentation!

Stackhero provides you with a fully managed Mosquitto MQTT cloud environment, designed for reliability and flexibility:

• Unlimited message throughput and data transfers, so your workflows never encounter artificial limits.
• Unlimited device authentication through your own external API, making onboarding and access management simple.
• Advanced ACLs for precise control over topics, users, and actions.
• A custom domain name with built-in HTTPS for secure, branded endpoints (for example: https://mqtt.your-company.com).
• Effortless updates: apply improvements or security patches with a single click.
• Consistent performance and enhanced security, with every instance running on a private, dedicated infrastructure.

Accelerate your IoT projects and reduce operational overhead. You can have a secure, production-ready Mosquitto MQTT cloud hosting instance up and running in just a few minutes.

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