MQTT

Use MQTT when a broker is a better fit than a direct WSS or HTTPS connection.

MQTT is still a secure public protocol. Clients connect to the broker with TLS, authenticate with per-client credentials, and publish only to the topics allowed for that client.

When To Use MQTT

Edge clients

Devices or small services need a broker-mediated path.

Network boundaries

The client can reach a broker more reliably than a direct hub route.

Fan-in traffic

Many clients need isolated topic access through one public broker endpoint.

Not the default

Use WSS first unless MQTT solves a real deployment problem.

What Must Exist

MQTT is enabled on the hub. WSS can stay the default while MQTT is optional.
The broker is reachable over TLS. Public clients should use mqtts://.
The client identity includes MQTT credentials. Create or download a fresh identity after enabling MQTT.
Topic access is scoped to the client. The SDK should publish and subscribe only through the returned topic prefix or explicit topics.

Credential Shape

The client identity may include this block:

{
  "mqtt": {
    "endpoint": "mqtts://mqtt.thalovant.com:8883",
    "username": "client-access-key",
    "password": "client-broker-password",
    "topic_prefix": "hubs/hub-id/clients/client-id",
    "c2s_topic": "hubs/hub-id/clients/client-id/c2s",
    "s2c_topic": "hubs/hub-id/clients/client-id/s2c",
    "status_topic": "hubs/hub-id/clients/client-id/status",
    "qos": 1,
    "tls": true
  }
}

Field	Meaning
`endpoint`	Broker URL. Public clients should use `mqtts://`.
`username`	Broker username for this client.
`password`	Broker password for this client.
`topic_prefix`	Topic scope used when explicit topics are not returned.
`c2s_topic`	Optional client-to-service topic.
`s2c_topic`	Optional service-to-client topic.
`status_topic`	Optional client status topic.
`qos`	MQTT quality of service, usually `1`.
`tls`	Whether the SDK should expect TLS.

Python

from thalovant import ThalovantClient, ThalovantControlPlane

api = ThalovantControlPlane()
api.login("[email protected]", "password")

result = api.create_client_identity(
    "hub-id",
    name="python-mqtt-client",
    preferred_protocols=("mqtt", "wss"),
)

identity = result.identity
if identity.mqtt is None:
    raise RuntimeError("MQTT is not available for this identity.")

with ThalovantClient(identity, protocol="mqtt") as client:
    print(client.ask("Reply over MQTT.").text)

Node.js

import { ThalovantClient, ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();
await api.login("[email protected]", "password");

const result = await api.createClientIdentity("hub-id", {
  name: "node-mqtt-client",
  preferredProtocols: ["mqtt", "wss"],
});

if (!result.identity.mqtt) {
  throw new Error("MQTT is not available for this identity.");
}

const client = new ThalovantClient(result.identity, { protocol: "mqtt" });
try {
  const reply = await client.ask("Reply over MQTT.");
  console.log(reply.text);
} finally {
  await client.close();
}

Go

result, err := control.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
  Name: "go-mqtt-client",
  PreferredProtocols: []thalovant.HubProtocol{
    thalovant.ProtocolMQTT,
    thalovant.ProtocolWSS,
  },
})
if err != nil {
  log.Fatal(err)
}
if result.Identity.MQTT == nil {
  log.Fatal("MQTT is not available for this identity.")
}

client, err := thalovant.NewClientWithOptions(result.Identity, thalovant.ClientOptions{
  Protocol: thalovant.ProtocolMQTT,
})
if err != nil {
  log.Fatal(err)
}
defer client.Close(ctx)

Rust

let result = control
    .create_client_identity_for_hub_id(
        "hub-id",
        BootstrapIdentityOptions {
            name: "rust-mqtt-client".into(),
            preferred_protocols: vec![HubProtocol::Mqtt, HubProtocol::Wss],
            ..Default::default()
        },
    )
    .await?;

if result.identity.mqtt.is_none() {
    panic!("MQTT is not available for this identity.");
}

let client = Client::with_protocol(result.identity.clone(), HubProtocol::Mqtt)?;

Common Issues

Symptom	Check
The SDK says MQTT is unsupported	Enable MQTT on the hub and create a fresh identity.
The identity has no `mqtt` block	The identity was created before MQTT was enabled or the workspace cannot use that protocol.
Broker auth fails	Rotate the client identity and confirm the app is using the latest broker password.
TLS fails	Use the `mqtts://` endpoint and confirm the broker certificate is valid.
Messages are ignored	Do not override SDK topics unless the identity returned explicit topics.