MQTT transports

Connect to CloudSignal over TLS for backends or WSS for browsers. Two encrypted transports, same MQTT protocol.

CloudSignal exposes the same MQTT 3.1.1 / 5.0 protocol over two transports. Both are encrypted with TLS 1.2 or higher. There is no unencrypted variant.

The two endpoints

Transport	URL	Best for
MQTT over TLS	`mqtts://mqtt.cloudsignal.app:8883`	Backend services, native MQTT clients, Node.js workers, Python services
MQTT over WSS	`wss://connect.cloudsignal.app:18885/`	Browser clients, mobile webviews, environments behind restrictive firewalls

Same broker, same credentials, same topics. Pick the transport that matches your runtime.

MQTT over TLS

Native MQTT over a TLS-encrypted TCP socket. Lowest overhead per message. Use this from anywhere your code can open a raw socket.

Aspect	Value
URL	`mqtts://mqtt.cloudsignal.app:8883`
Encryption	TLS 1.2+
Best for	Backend services, native MQTT clients, IoT gateways
Overhead	Low (no HTTP framing)

Node.js (SDK)

import CloudSignal from '@cloudsignal/mqtt-client';

const client = new CloudSignal({ preset: 'server' });

await client.connectWithToken({
  organizationId: process.env.CLOUDSIGNAL_ORG_ID,
  secretKey: process.env.CLOUDSIGNAL_SECRET_KEY,
  userEmail: 'service@example.com',
});

Python (paho-mqtt)

import ssl
import paho.mqtt.client as mqtt

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.username_pw_set('agent-01@org_k7xm4pqr2n5t', 'your-password')
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.connect('mqtt.cloudsignal.app', 8883)
client.loop_forever()

MQTT framed inside WebSocket Secure. Required for browser clients (browsers can't open raw TCP). Also useful when corporate firewalls block non-HTTP egress, since WSS travels over the same TLS channel as https://.

Aspect	Value
URL	`wss://connect.cloudsignal.app:18885/`
Encryption	TLS 1.2+ via WebSocket
Best for	Browsers, mobile webviews, firewalled environments
Overhead	Slight WebSocket framing

Browser (SDK)

import CloudSignal from '@cloudsignal/mqtt-client';

const client = new CloudSignal({ preset: 'desktop' });

await client.connectWithToken({
  organizationId: process.env.NEXT_PUBLIC_CLOUDSIGNAL_ORG_ID,
  externalToken: session.access_token,
});

The SDK uses the WSS endpoint automatically in browser presets (desktop, mobile). You don't have to pass the host yourself.

Choosing a transport

You are building	Use
Browser app, mobile webview, embed widget	WSS
Node.js / Python / Go backend, CLI tool	TLS
Mobile native (iOS / Android)	Either - SDKs default to WSS for compatibility
Serverless function	TLS (server-side runtimes can open raw sockets)
Gateway forwarding from non-MQTT devices	TLS

Both endpoints are encrypted and use the same authentication, ACL rules, and quota. You don't need to choose for security reasons - only for runtime compatibility.

Token authentication on both transports

Server-side tokens work identically over TLS and WSS. Mint a token on your backend, hand it to the client, and connect. The Token exchange API is transport-agnostic.

Next steps

Connect from JavaScript - Browser + Node.js quickstart
Python quickstart - paho-mqtt and aiomqtt on TLS
Server-side tokens - Browser auth via WSS without exposing secrets
Connection parameters - Full reference for both endpoints

On this page