Common ACL patterns

Copy these patterns for typical MQTT architectures. Use this as a starting point when you need ACL rules for agent fleets, chat, multi-tenant apps, or admin tooling.

Agent fleet

Agent state to backend

Agents publish state; backend collects it.

# Agents can only publish to their own state topic
User:       agent-%
Topic:      agents/%u/state
Permission: publish

# Backend subscribes to all agent state
User:       backend-collector
Topic:      agents/#
Permission: subscribe

Bidirectional agent communication

Agents send state up, receive tasks down.

# Agents publish state
User:       agent-%
Topic:      agents/%u/state
Permission: publish

# Agents receive tasks
User:       agent-%
Topic:      agents/%u/inbox
Permission: subscribe

# Backend has full access
User:       backend-service
Topic:      agents/#
Permission: pubsub

Coordinator pattern

Multiple agents behind a coordinator.

# Coordinator publishes on behalf of its agents
User:       coordinator-%
Topic:      coordinators/%u/agents/+/state
Permission: publish

# Coordinator receives configuration
User:       coordinator-%
Topic:      coordinators/%u/config
Permission: subscribe

# Backend full access
User:       backend
Topic:      coordinators/#
Permission: pubsub

Real-time applications

Chat application

Users can send and receive in their rooms.

# Users can publish to rooms they're in
User:       user-%
Topic:      rooms/+/messages
Permission: publish

# Users subscribe to room messages
User:       user-%
Topic:      rooms/+/messages
Permission: subscribe

# Users receive private messages
User:       user-%
Topic:      users/%u/inbox
Permission: subscribe

# Users send private messages to anyone
User:       user-%
Topic:      users/+/inbox
Permission: publish

Collaborative editing

Document changes with presence.

# Users publish their changes
User:       editor-%
Topic:      docs/+/changes
Permission: publish

# Users subscribe to all changes
User:       editor-%
Topic:      docs/+/changes
Permission: subscribe

# Presence updates
User:       editor-%
Topic:      docs/+/presence
Permission: pubsub

Live notifications

Server pushes to clients.

# Server publishes notifications
User:       notification-server
Topic:      notifications/#
Permission: publish

# Users subscribe to their notifications
User:       user-%
Topic:      notifications/%u
Permission: subscribe

# Broadcast notifications
User:       user-%
Topic:      notifications/broadcast
Permission: subscribe

Multi-tenant patterns

Customer isolation

Complete separation between customers.

# Customer A
User:       tenant-a-%
Topic:      tenants/a/#
Permission: pubsub

# Customer B
User:       tenant-b-%
Topic:      tenants/b/#
Permission: pubsub

# Admin can see all
User:       admin
Topic:      tenants/#
Permission: subscribe

Shared topics + private

Common broadcast with private channels.

# Everyone can subscribe to announcements
User:       %
Topic:      announcements
Permission: subscribe

# Only admins can publish announcements
User:       admin-%
Topic:      announcements
Permission: publish

# Private topics per customer
User:       customer-%
Topic:      private/%u/#
Permission: pubsub

Monitoring and diagnostics

Status dashboard

Agents report status; dashboard displays.

# Agents publish status
User:       agent-%
Topic:      agents/%u/state
Permission: publish

# Dashboard subscribes to all status
User:       dashboard
Topic:      agents/#
Permission: subscribe

# Agents publish heartbeats
User:       agent-%
Topic:      heartbeat/%u
Permission: publish

# Monitoring subscribes to heartbeats
User:       monitoring
Topic:      heartbeat/#
Permission: subscribe

Logging

Centralized log collection.

# All services can publish logs
User:       %
Topic:      logs/%u
Permission: publish

# Log aggregator collects all
User:       log-aggregator
Topic:      logs/#
Permission: subscribe

Access control patterns

Admin full access

User:       admin
Topic:      #
Permission: pubsub

Use sparingly. Prefer specific rules even for admin accounts.

Read-only monitoring

# Can see everything, change nothing
User:       monitor
Topic:      #
Permission: subscribe

Write-only ingestion

# Can send data, can't read anything
User:       data-source-%
Topic:      ingest/%u
Permission: publish

Mobile app patterns

User-specific channels

# User subscribes to their updates
User:       mobile-%
Topic:      users/%u/updates
Permission: subscribe

# User can publish actions
User:       mobile-%
Topic:      users/%u/actions
Permission: publish

# Backend processes actions and sends updates
User:       api-backend
Topic:      users/#
Permission: pubsub

Push notifications

# Mobile clients subscribe to push
User:       mobile-%
Topic:      push/%u
Permission: subscribe

# Push service sends notifications
User:       push-service
Topic:      push/#
Permission: publish

Quick reference

Use case	User pattern	Topic pattern	Permission
Agent state	`agent-%`	`agents/%u/state`	publish
Agent inbox	`agent-%`	`agents/%u/inbox`	subscribe
Backend collector	`backend`	`agents/#`	subscribe
Backend dispatcher	`backend`	`commands/#`	publish
Chat messages	`user-%`	`rooms/+/messages`	pubsub
Notifications	`user-%`	`notifications/%u`	subscribe
Admin full access	`admin`	`#`	pubsub
Monitoring	`monitor`	`#`	subscribe

Next steps

Create your rules - Apply these patterns
Topic pattern syntax - Deep dive on wildcards

On this page