How CloudSignal works

CloudSignal's architecture, connection flows, and the publish/subscribe model that powers real-time communication.

CloudSignal is a managed MQTT broker that routes real-time messages between your devices, applications, and services. This page covers the core concepts you'll touch when integrating.

The publish/subscribe model

MQTT uses a publish/subscribe (pub/sub) pattern:

Publishers send messages to topics (for example, agents/agent-01/state)
Subscribers listen to topics they care about
The broker (CloudSignal) routes messages from publishers to all matching subscribers

Unlike HTTP request/response, pub/sub is:

Property	What it means
Asynchronous	Publishers don't wait for subscribers
Decoupled	Publishers and subscribers don't need to know about each other
Efficient	One message reaches many subscribers instantly

Publish / subscribe

Client A

Publisher

CloudSignal broker

Client B

Subscriber

Client C

Subscriber

Client D

Subscriber

Connection options

CloudSignal exposes two encrypted endpoints. Pick the one that matches where your code runs.

MQTT over TLS

Aspect	Value
URL	`mqtts://mqtt.cloudsignal.app:8883`
Best for	Backend services, native MQTT clients, IoT gateways
Encryption	TLS 1.2+

MQTT over WSS

Aspect	Value
URL	`wss://connect.cloudsignal.app:18885/`
Best for	Browser apps, mobile webviews, environments behind restrictive firewalls
Encryption	TLS 1.2+

For browser apps, use the WSS endpoint with server-side token authentication. Never expose long-lived credentials in client-side code. See Server-side tokens.

Authentication flow

CloudSignal authenticates clients against your organization. The username always carries the organization ID.

Authentication flow

Client

CloudSignal

1. CONNECT username@org_id + password

2. Validate org, user, password

3. CONNACK + apply ACL rules

Two authentication methods

Method	When to use	Lifetime
Individual users	Backend services, IoT devices	Permanent until rotated
Temporary tokens	Browser apps	60-minute default TTL

# Individual user
Username: mydevice@org_k7xm4pqr2n5t
Password: devicepassword123

# Temporary token
Username: token_user_xyz@org_k7xm4pqr2n5t
Password: tkn_abc123def456

Topics and ACLs

Topics are hierarchical paths that organize your messages.

chat/conv-7/messages
chat/conv-7/typing
notifications/user-42/inbox
agents/agent-01/state
agents/agent-01/inbox

Wildcards let you subscribe to multiple topics at once.

Wildcard	Matches	Example
`+`	One level	`chat/+/messages` matches every room's messages
`#`	All remaining levels	`chat/#` matches everything under `chat/`

ACLs (access control lists) define what each user can do.

User: agent-01@org_k7xm4pqr2n5t
  - PUBLISH:   agents/agent-01/#
  - SUBSCRIBE: agents/agent-01/inbox

User: dashboard@org_k7xm4pqr2n5t
  - PUBLISH:   commands/#
  - SUBSCRIBE: agents/#

Quality of Service (QoS)

MQTT supports three QoS levels:

QoS	Guarantee	Best for
0	At most once (fire and forget)	High-frequency telemetry where occasional loss is acceptable
1	At least once (may duplicate)	Important messages where duplicates can be handled
2	Exactly once	Critical operations like commands or transactions

Higher QoS adds overhead. Use QoS 0 for telemetry; reach for QoS 1 or 2 only when delivery guarantees are required.

Sessions and message retention

Persistent sessions

When a client connects with clean_session=false:

Step	What happens
Connect	CloudSignal records the client's subscriptions
Disconnect	Messages matching those subscriptions are queued
Reconnect	Queued messages are delivered

This enables offline-tolerant apps where clients can miss messages and catch up later.

Retained messages

When you publish with retain=true:

The broker stores the last message on that topic
New subscribers immediately receive the retained message
Useful for "last known state" scenarios

# Publish retained message
PUBLISH agents/agent-01/state: {"status":"idle"} (retain=true)

# Later, a new subscriber connects
SUBSCRIBE agents/agent-01/state
-> Immediately receives: {"status":"idle"}

Organization isolation

Every CloudSignal account belongs to an organization.

Users, ACLs, and quotas are scoped to the organization
Organizations are completely isolated from each other
You can create many users within one organization
The organization ID is part of every username: user@organization_id

When you sign up, an organization is created for you automatically.

Next steps

Create your first MQTT user - Set up credentials in the dashboard
Set up ACL rules - Lock down which topics each user can touch
Connect from Next.js - Browser quickstart with server-side tokens

On this page