Skip to main content
MQTT users define authentication credentials and permissions for devices and services connecting to the MQTT broker.

​
List MQTT Users

GET /api/v1/mqtt-users
Retrieves all MQTT user accounts.

​
Response

​
id
integer
Unique MQTT user identifier
​
username
string
MQTT username for authentication
​
tenantId
integer
Associated tenant ID
​
deviceType
string
Device type: SENSOR, ACTUATOR, GATEWAY, API
​
isActive
boolean
Whether this user can currently connect
​
createdAt
string
Timestamp when user was created
​
lastConnectedAt
string
Timestamp of last successful connection (null if never connected)

​
Example

cURL
curl -X GET "https://api.example.com/api/v1/mqtt-users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response
[
  {
    "id": 1,
    "username": "sensor_gh001",
    "tenantId": 1,
    "deviceType": "SENSOR",
    "isActive": true,
    "createdAt": "2025-01-15T10:30:00Z",
    "lastConnectedAt": "2025-03-03T22:15:30Z"
  },
  {
    "id": 2,
    "username": "actuator_pump01",
    "tenantId": 1,
    "deviceType": "ACTUATOR",
    "isActive": true,
    "createdAt": "2025-01-15T10:35:00Z",
    "lastConnectedAt": "2025-03-03T22:10:15Z"
  }
]

​
Get MQTT User by ID

GET /api/v1/mqtt-users/{id}
​
id
integer
required
MQTT user ID

​
Example

cURL
curl -X GET "https://api.example.com/api/v1/mqtt-users/1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Create MQTT User

POST /api/v1/mqtt-users
Creates a new MQTT user with authentication credentials.

​
Request Body

​
username
string
required
Unique MQTT username (3-50 characters)
​
password
string
required
MQTT password (minimum 8 characters, hashed with bcrypt)
​
tenantId
integer
required
Tenant ID this user belongs to
​
deviceType
string
required
Device type: SENSOR, ACTUATOR, GATEWAY, API

​
Example

cURL
curl -X POST "https://api.example.com/api/v1/mqtt-users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "sensor_gh002",
    "password": "SecureP@ssw0rd!",
    "tenantId": 1,
    "deviceType": "SENSOR"
  }'
Store passwords securely! The API hashes passwords with bcrypt before storing. The plain-text password cannot be retrieved later.

​
Update MQTT User

PUT /api/v1/mqtt-users/{id}
​
id
integer
required
MQTT user ID

​
Request Body

All fields are optional for updates.
​
password
string
New password (will be hashed with bcrypt)
​
deviceType
string
Updated device type
​
isActive
boolean
Activate or deactivate the user

​
Example

cURL
curl -X PUT "https://api.example.com/api/v1/mqtt-users/1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

​
Delete MQTT User

DELETE /api/v1/mqtt-users/{id}
​
id
integer
required
MQTT user ID
Deleting an MQTT user immediately revokes their access. Connected devices will be disconnected on their next message.

​
Example

cURL
curl -X DELETE "https://api.example.com/api/v1/mqtt-users/1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Device Types

MQTT users are categorized by device type for access control:

​
SENSOR

  • Purpose: Greenhouse sensor devices
  • Permissions: Publish sensor data to GREENHOUSE/{tenantId}
  • Example: Temperature sensors, humidity sensors, soil moisture

​
ACTUATOR

  • Purpose: Control devices (pumps, valves, windows)
  • Permissions:
    • Subscribe to command topics
    • Publish status updates
  • Example: Irrigation pumps, ventilation systems, shade controllers

​
GATEWAY

  • Purpose: Edge gateways that aggregate multiple sensors
  • Permissions:
    • Publish data for multiple devices
    • Subscribe to configuration updates
  • Example: Raspberry Pi gateway, industrial IoT gateway

​
API

  • Purpose: Backend services and integrations
  • Permissions: Full access (publish and subscribe to all topics)
  • Example: Analytics services, monitoring dashboards, third-party integrations

​
Access Control Lists (ACLs)

ACL rules are automatically created based on device type:
Device TypePublish TopicsSubscribe Topics
SENSORGREENHOUSE/{tenantId}GREENHOUSE/{tenantId}/commands/#
ACTUATORGREENHOUSE/{tenantId}/status/#GREENHOUSE/{tenantId}/actuators/#
GATEWAYGREENHOUSE/{tenantId}/#GREENHOUSE/{tenantId}/#
API# (all topics)# (all topics)
ACL permissions are enforced at the MQTT broker level using the EMQX authentication plugin.

​
Security Best Practices

Strong Passwords

Use minimum 12 characters with uppercase, lowercase, numbers, and symbols

Unique Credentials

Each device should have its own unique MQTT username and password

Regular Rotation

Rotate MQTT passwords every 90 days for production environments

Monitor Access

Track lastConnectedAt to detect unused or compromised accounts

​
Testing MQTT Authentication

Test MQTT credentials using mosquitto_pub: 
mosquitto_pub \
  -h mqtt.example.com \
  -p 1883 \
  -u "sensor_gh001" \
  -P "your_password" \
  -t "GREENHOUSE/1" \
  -m '{"TEMPERATURA INVERNADERO 01": 25.5}'
If authentication succeeds, the message will be published. If it fails, you’ll receive an authentication error.
For production, use TLS/SSL (port 8883) instead of plain MQTT (port 1883).

Build docs developers (and LLMs) love

Get started for freeTalk to us