Devices and topic policies

RunMQTT separates a device identity from the topic rules assigned to it. This keeps credentials narrow and makes access reviews easier as a fleet grows.

Policy templates

A template represents one device role. Examples include a read-only dashboard, a field sensor, a gateway, or a command service. Devices created from the same template receive the same topic policy set without sharing credentials.

Each policy contains:

• a topic filter;
• a permission: publish, subscribe, or both;
• an optional description for reviewers.

Topic filter design

Use stable, hierarchical topics that describe ownership before payload type:

tenants/acme/sites/shanghai/devices/sensor-42/telemetry
tenants/acme/sites/shanghai/devices/sensor-42/state
tenants/acme/sites/shanghai/devices/sensor-42/commands

The + wildcard matches one topic level. The # wildcard matches the remaining tree and should be reserved for trusted gateway or backend identities.

Prefer separate filters for telemetry and commands. A sensor that publishes telemetry usually does not need permission to publish commands, and a dashboard that subscribes to state rarely needs device-level publish access.

Device credentials

Copy the MQTT username and password from the dashboard directly into your client. The username is <broker-id>/<device-name> and the password is the original device secret; no additional calculation is needed.

Every device has its own generated connection credentials. A credential belongs to one broker and one policy template. Deleting a device identity does not change the account login or other devices. Use Reset password in device details to generate a new password for the same identity; see troubleshooting.

Use a different client ID for each concurrent connection, even when testing the same device secret from multiple clients. Broker connection accounting treats simultaneous client IDs as separate connections.

Safe rollout pattern

1. Create the template with the minimum topic set.
2. Create one test device from that template.
3. Verify permitted publish and subscribe operations.
4. Verify that an out-of-scope topic is rejected.
5. Add production devices only after the policy behaves as expected.

Changes to a shared template can affect every attached device. Review wildcard changes with the same care as application authorization changes.

A sensor and a backend service

In your Broker, create two templates and add these policies before creating their devices:

Create a device from each template and use its own credentials in each client. Subscribe the backend to devices/+/telemetry, then publish from the sensor to devices/sensor-42/telemetry. Reverse the direction for commands. Wait for successful subscriptions before publishing.

The backend may receive every matching sensor's telemetry. The sensor-42 template grants only that sensor's paths. Attaching another device to that same template grants the same access; the template name and Client ID do not create isolation or substitute topic variables. Create appropriately scoped policies for other devices.

Filter matching and permission checks

• Topic names are case-sensitive; demo/hello differs from Demo/hello and /demo/hello.
• Publish to a concrete topic without wildcards. + must occupy one whole level; # must occupy the final whole level in a subscription filter.
• devices/+/telemetry matches devices/sensor-42/telemetry, but not devices/sensor-42/status or devices/site-a/sensor-42/telemetry.
• A filter grants permission; clients must still send SUBSCRIBE. Prefer an exact allowed filter first. A broader subscription can be rejected even when one matching concrete topic is allowed.
• A broad # grant can preserve access after a narrower rule is removed. Audit all rules on the template, not just the most recent edit.

Use the template's policy test or the ACL linter for a local review, then confirm allowed and denied operations with real clients. Do not test negative cases by sending sensitive data. For group consumption, use the actual topic permissions and the client format in shared subscriptions.

Names and changes

Device names accept 1–40 ASCII letters, digits, hyphens or underscores. Broker and template names accept 2–80 characters; policy filters accept up to 180 characters. These are form constraints, not a guarantee that arbitrary topics or traffic rates are supported.

Before deleting a template, remove its attached devices. Deleting a device revokes that identity; it does not cancel the Broker subscription. Replace credentials and validate live access using the steps in troubleshooting.

Reset a device password

Open the device details page or its credentials side panel and choose Reset password. Review the warning and confirm. The new password stays masked until you reveal or copy it. Update all clients using this device, then reconnect with the new password and verify an allowed publish and subscription.

The previous password stops authenticating new connections immediately. The username, device name, Client ID and template policies remain unchanged. Existing connections may remain online until they reconnect; resetting a password is not a guaranteed immediate disconnect. Check that the old password cannot open a new connection.

If RunMQTT cannot confirm the result, do not assume the old password still works. Reload the credentials; if the password is unavailable, reset again and deploy the latest value. Avoid simultaneous resets from multiple tabs.