Creating ACL rules

Walk through creating ACL rules to control topic access for your MQTT clients. Use this guide when you need to restrict who can publish to or subscribe from specific topics.

Prerequisites

At least one MQTT client created
Access to the CloudSignal dashboard

The ACL editor

CloudSignal uses a JSON-based ACL editor for creating and managing rules. Rules are organized into rule sets, named groups of ACL rules that make your access control easier to manage.

Key features

Feature	Description
JSON editor	Edit rules directly in a syntax-highlighted JSON editor
Named rule sets	Organize rules into logical groups (for example, "Agents", "Backend")
Default locked rule	A deny-all rule that ensures security by default
Priority-based matching	Rules are evaluated in order; first match wins

The default locked rule denies all access by default. You must explicitly create rules to allow access.

Creating rules

Navigate to ACL rules

Log into the CloudSignal dashboard
Click ACL Rules under Connections in the sidebar

Open the JSON editor

Click the Edit Rules button to open the JSON editor.

Add a rule set

Rules are defined as a JSON array. Each rule object contains:

User pattern

Enter the username(s) this rule applies to:

agent-001          # Exact match - only this user
agent-%            # Pattern match - any user starting with "agent-"
%                  # All users (use with caution)

The % character is a wildcard that matches any characters in the username.

Topic pattern

Enter the MQTT topic(s) to allow access to:

agents/state                  # Exact topic
agents/+/state                # Single-level wildcard
agents/#                      # Multi-level wildcard

See Topic patterns for detailed wildcard information.

Permission type

Select the access level:

Permission	Description
publish	User can send messages to this topic
subscribe	User can receive messages from this topic
pubsub	User can both publish and subscribe

Save the rule

Click Create or Save
The rule takes effect immediately
Existing connections will be affected on next publish/subscribe attempt

JSON format

Here's an example ACL configuration in JSON:

[
  {
    "name": "Agent State Publishing",
    "rules": [
      {
        "username": "agent-%",
        "topic": "agents/%u/state",
        "permission": "publish"
      },
      {
        "username": "agent-%",
        "topic": "agents/%u/inbox",
        "permission": "subscribe"
      }
    ]
  },
  {
    "name": "Backend Full Access",
    "rules": [
      {
        "username": "backend-service",
        "topic": "agents/#",
        "permission": "pubsub"
      },
      {
        "username": "backend-service",
        "topic": "commands/#",
        "permission": "pubsub"
      }
    ]
  }
]

Example rules

Agent publishes to its own topic

Allow an agent to publish only to its specific topic:

{
  "username": "agent-001",
  "topic": "agents/agent-001/state",
  "permission": "publish"
}

Agent subscribes to its inbox

Allow an agent to receive tasks:

{
  "username": "agent-001",
  "topic": "agents/agent-001/inbox",
  "permission": "subscribe"
}

Backend can access all agent topics

Allow your backend service full access:

{
  "username": "backend-service",
  "topic": "agents/#",
  "permission": "pubsub"
}

Pattern: all agents publish to their topics

Using %u substitution:

{
  "username": "agent-%",
  "topic": "agents/%u/state",
  "permission": "publish"
}

%u is replaced with the connecting username. So agent-001 can publish to agents/agent-001/state.

Managing rules

View existing rules

Go to ACL Rules
Browse or search the rule list
Click a rule to view details

Edit a rule

Go to ACL Rules
Click on the rule row
Modify and save

Delete a rule

Go to ACL Rules
Click on the rule
Click Delete
Confirm deletion

Deleting a rule takes effect immediately. Active connections may lose access to topics.

Rule evaluation

When a user tries to publish or subscribe, CloudSignal checks:

Does the user have any ACL rules?
Does any rule match the topic and action?
If yes, allow.
If no matching rule, deny.

User: agent-001 wants to PUBLISH to "agents/agent-001/state"

Rules for agent-001:
  agents/+/inbox      -> subscribe (no match - wrong topic + action)
  agents/agent-001/state -> publish (MATCH)

Result: ALLOWED

Best practices

Start restrictive

Create specific rules rather than broad ones:

Good: agent-001 -> agents/agent-001/# -> pubsub
Bad:  agent-001 -> #                  -> pubsub

Use patterns for groups

Instead of individual rules:

Good: agent-% -> agents/%u/state -> publish  (1 rule for all agents)
Bad:  agent-001 -> agents/agent-001/state -> publish
      agent-002 -> agents/agent-002/state -> publish
      ... (100 rules)

Be explicit about data flow direction:

# Agents publish state
agent-% -> agents/%u/state -> publish

# Agents receive tasks
agent-% -> agents/%u/inbox -> subscribe

# Backend does both
backend -> agents/#  -> subscribe
backend -> commands/# -> publish

Document your rules

Use consistent naming and keep a record of your ACL strategy:

# Agent state flow
agent-% -> agents/%u/state -> publish
agent-% -> agents/%u/inbox -> subscribe

# Mobile app access
app-% -> users/%u/notifications -> subscribe
app-% -> users/%u/actions       -> publish

Next steps

Topic patterns - Master wildcards
Common ACL patterns - Ready-to-use examples
MQTT topics explained - Topic fundamentals

On this page