A multi-tenant MQTT broker serves many independent customers or teams from shared infrastructure while keeping each one's messages, identities and resource usage separate. This article walks through the building blocks of that architecture, namespaces, credentials and quotas, the trade-offs between them, and the questions to ask a provider. You will finish with a mental model you can use to design your own platform or evaluate someone else's.
What Multi-Tenancy Means for an MQTT Broker
In MQTT, every client connects to a broker and publishes to or subscribes on topics. A plain broker has one flat topic space: any client allowed to subscribe to # sees everything. That is fine for a single application, and dangerous the moment two customers share the same server.
A tenant is a unit of isolation: a customer, a business unit, an environment such as staging, or a product line. Multi-tenancy means the broker treats each tenant as if it had its own private broker, even though connections land on the same processes and machines. To get there, the architecture has to answer three questions for every connection and every message:
- Which tenant does this client belong to? (identity)
- Which topics can this client see and write? (namespace)
- How much of the shared capacity may this tenant consume? (resources)
If you need a refresher on brokers in general, read about what an MQTT broker does first.
Building Block 1: Tenant Namespaces
Topic Prefixes
The simplest approach is a convention: every tenant's topics begin with a prefix, such as tenant-42/site-a/line-1/temperature. The broker, or an authorization layer in front of it, must then enforce that a client from tenant 42 can only use topics under tenant-42/. Without enforcement, a prefix is merely tidy naming, not isolation.
Mountpoints and Virtual Hosts
Some brokers support mountpoints or similar mechanisms: the broker silently prepends a tenant-specific prefix to every topic a client uses. The client publishes to sensors/temp, and the broker stores and routes it as tenant-42/sensors/temp. Clients cannot even express a topic outside their namespace, and a subscription to # only matches inside the tenant's space. This is stronger than convention because it does not rely on correct client behavior.
Separate Logical Brokers
The strongest logical model gives each tenant its own broker instance identity, with its own credentials, its own session store and its own retained messages, even if the underlying cluster is shared. A wildcard subscription in one tenant can never match a topic in another, because they do not share a topic tree at all.
Building Block 2: Identity and Credentials
Isolation starts at CONNECT. A robust design ties each credential to exactly one tenant and checks it before any topic operation is accepted.
- Per-tenant credentials. Usernames and passwords, tokens or client certificates are issued per tenant, ideally per device.
- Client ID binding. Binding the client ID to the issued credential stops one device from impersonating another and from hijacking someone else's session, since MQTT disconnects the older connection when a duplicate client ID connects.
- Brute-force protection. Shared infrastructure is a bigger target. Rate limiting and blocking addresses after repeated failed logins protect every tenant at once.
- Secret rotation. Tenants need a way to rotate credentials without asking the operator to restart anything.
Building Block 3: Resource Quotas and Noisy Neighbors
The noisy-neighbor problem is the classic risk of shared infrastructure. One tenant's firmware bug that reconnects in a tight loop, or a script that publishes as fast as it can, can consume CPU, memory and bandwidth that other tenants need. Quotas turn that risk into a bounded, per-tenant problem.
| Resource | Why limit it | Typical enforcement |
|---|---|---|
| Concurrent connections | Memory and file descriptors per connection | Reject CONNECT above the limit |
| Message rate | CPU and fan-out cost | Throttle or disconnect, MQTT 5 reason code |
| Maximum message size | Memory spikes, bandwidth | Reject oversize PUBLISH |
| Subscriptions per client | Routing table size | Reject SUBSCRIBE above the limit |
| QoS level | Inflight state and retries | Downgrade or reject |
| Session expiry | Stored offline messages | Cap the expiry interval |
| Retained messages | Storage | Count and size limits |
MQTT 5 helps here because the broker can explain itself. Reason code 0x97 (Quota exceeded) tells a well-written client that it hit a limit, rather than leaving it to guess why a publish was dropped. For the client side of limits, see MQTT broker connection quotas.
Shared Cluster or Dedicated Cluster?
Multi-tenancy is a spectrum. At one end, every tenant shares one cluster with logical isolation. At the other, each tenant gets dedicated machines. The table summarizes the trade-off.
| Aspect | Shared multi-tenant cluster | Dedicated cluster per tenant |
|---|---|---|
| Cost efficiency | High, capacity is pooled | Lower, capacity is reserved |
| Isolation | Logical (identity, namespace, quotas) | Physical |
| Noisy-neighbor exposure | Limited by quotas | None from other tenants |
| Time to provision | Seconds | Longer |
| Custom limits | Plan-based | Sized to the tenant |
| Typical use | Prototypes, small and mid-size fleets | Large fleets, strict requirements |
Most providers offer both and let a tenant move from one to the other as needs grow. The deeper question of how strongly to separate customers is covered in MQTT tenant isolation.
Operating a Multi-Tenant Broker
Designing isolation is half the work. Operating it is the other half:
- Per-tenant observability. Metrics need a tenant dimension: connections, message rates and quota rejections per tenant, not just cluster totals.
- Fair upgrades. Rolling restarts should spread reconnect load, and clients must use randomized backoff so thousands of devices from many tenants do not return at the same instant.
- Abuse handling. Flood protection must act on the offending tenant or client, not the whole cluster.
- Tenant lifecycle. Creating, suspending and deleting tenants must clean up sessions, retained messages and credentials completely.
How ConnectMQ Implements Multi-Tenancy
ConnectMQ is built as a multi-tenant platform. On the Serverless plans, many brokers share a cluster, and each broker is isolated from the others: it has its own generated username, password and client ID, client IDs are bound to the issued credentials, and per-plan quotas cap connections, QoS and message size. The free Serverless plan allows up to 25 connections, QoS up to 1 and 256 KB messages; the paid Serverless plan raises that to up to 1,000 connections, QoS 2, 1 MB messages and shared subscriptions.
Flood protection and IP blocking after repeated failed logins protect every tenant on the shared cluster. When a client exceeds its limits, MQTT 5 clients receive reason code 0x97 so the cause is visible. If logical isolation is not enough, the Dedicated plan gives you an isolated cluster, and BYOC runs the broker in your own cloud account while ConnectMQ still manages it.
Try a Tenant-Scoped Topic Layout
Even inside your own broker, a consistent topic layout makes multi-tenant applications easier to reason about. This MQTT.js example publishes to a tenant-and-site prefixed topic on the public MQTT test broker; remember that the public area is readable by everyone.
const mqtt = require("mqtt");
const tenant = "tenant-demo-91b2";
const base = `connectmq/demo/${tenant}`;
const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
clientId: `${tenant}-gw-01`,
protocolVersion: 5,
});
client.on("connect", () => {
client.subscribe(`${base}/+/+/temperature`, { qos: 1 });
setInterval(() => {
const payload = JSON.stringify({ value: 20 + Math.random() * 5, ts: Date.now() });
client.publish(`${base}/site-a/line-1/temperature`, payload, { qos: 1 });
}, 5000);
});
client.on("message", (topic, message) => console.log(topic, message.toString()));
client.on("error", (err) => console.error("MQTT error:", err.message));
On a private ConnectMQ broker, add username: "YOUR_USERNAME" and password: "YOUR_PASSWORD" and use YOUR_CLIENT_ID from the portal.
Get Started with ConnectMQ
Skip building tenant isolation yourself. Create a free, isolated Serverless broker at app.connectmq.com, with no credit card required, and scale to Dedicated or BYOC when you need stronger separation. Learn more about the hosted MQTT broker model, or see the full cloud MQTT broker guide.
Frequently Asked Questions
Is a topic prefix enough to separate tenants?
Only if the broker enforces it. A prefix without enforcement is a naming convention; a client that subscribes to # would still see other tenants' messages.
What is the noisy-neighbor problem in MQTT?
It happens when one tenant's heavy or buggy traffic consumes shared broker resources and degrades service for others. Per-tenant quotas and flood protection limit the damage.
Does a multi-tenant broker affect my client code?
Usually not. Clients use standard MQTT; the tenant boundary is defined by the credentials and endpoint you connect with.
When should I move from a shared to a dedicated broker?
Move when you need predictable capacity that is not shared, limits above shared-plan quotas, or a policy that requires physical isolation.
