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

1. MQTT is enabled on the hub. WSS can stay the default while MQTT is optional.
2. The broker is reachable over TLS. Public clients should use mqtts://.
3. The client identity includes MQTT credentials. Create or download a fresh identity, or open Connection details, after enabling MQTT.
4. Topic access is scoped to the client. Publish and subscribe only under the topic_prefix the identity returns.

Credential Shape

When MQTT is enabled, the client identity carries an mqtt block:

{
  "mqtt": {
    "endpoint": "mqtts://mqtt.thalovant.com:8883",
    "username": "client-access-key",
    "password": "client-broker-password",
    "topic_prefix": "<namespace>/<hub-id>/<client-id>",
    "tls": true
  }
}

Field	Meaning
endpoint	Broker URL. Public clients should use mqtts://.
username	Broker username for this client. It is the client access key.
password	Broker password for this client.
topic_prefix	Full topic base for this client. Append a channel suffix instead of hardcoding a path.
tls	Whether the client should connect over TLS.

Caution

The broker password, hub password, and client static private key are secrets. Keep them in protected storage.

Topics

The identity’s topic_prefix is the full base for every topic this client uses. It looks like <namespace>/<hub-id>/<client-id>, where <client-id> is the client access key. Treat it as opaque: read topic_prefix from the identity and append the channel suffix instead of assembling the path yourself.

Channel	Topic	Purpose
Inbound	<topic_prefix>/in	The client publishes requests here.
Outbound	<topic_prefix>/out	The client subscribes here for replies.
Status	<topic_prefix>/status	Retained presence and status for this client.

Note

These channels are the protocol’s convention. What a client may actually publish or subscribe to is governed by the hub’s per-connection broker ACL. A subscribe can be refused — for example on <topic_prefix>/out or <topic_prefix>/status — until that connection’s ACL grants it. If replies never arrive after a successful connect, the connection’s ACL likely needs the subscribe grant.

Get MQTT Credentials

A client’s MQTT credentials come from its identity. To read them for a custom client:

1. Open the connection. In Connections, select the client, then open its Connection details panel.
2. Verify it is you. Confirm with your authenticator app or a recovery code. The panel is gated because it returns secrets.
3. Copy the broker credentials. Take the endpoint (mqtts://mqtt.thalovant.com:8883), username (the access key), broker password, and topic prefix. Keep the complete identity as well: its hub password is what authenticates the session with the hub. You can also download _identity.json.

If two-step sign-in blocks the panel, set it up first on Profile and Security.

Note

An existing connection may need to open Connection details once to pick up MQTT credentials after MQTT is enabled.

Custom MQTT Clients

You can connect any MQTT client to the broker with the credentials above, without Thalovant Voice or a managed runtime. Reaching the broker is the easy part.

The <topic_prefix>/in and <topic_prefix>/out topics carry the sign-in and authentication messages, followed by encrypted application messages. Subscribe to the outbound topic before sending anything. Encrypted messages are raw binary, not base64 or JSON; keep every chunk of one message in order and never replay a message.

A custom client must sign in to the broker and authenticate with the hub before sending application requests. Use the MQTT transport in a compatible Python, Node.js, Go, or Rust SDK, or drive the protocol with the embedded C library and your own transport. A broker connection alone is not an authenticated hub session.

Keep the SDK’s saved keys across reconnects. After the broker connection is lost, authenticate again before sending. Use different identities for client processes connected at the same time.

Caution

Always connect with mqtts:// and validate the broker certificate. TLS protects the broker credentials and the sign-in. The hub session is a second layer: it encrypts the application messages and proves the hub is the hub. Neither one replaces the other.

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	Use Python, server-side Node.js, Go, or Rust. Kotlin, Swift, .NET, and the Node browser build do not own an MQTT transport. Also confirm the hub and identity enable MQTT.
The identity has no mqtt block	Enable MQTT on the hub, then open Connection details or download a fresh identity to pick up broker credentials.
Broker auth fails	Confirm the username is the access key and the client uses the latest broker password. Rotate the identity if needed.
TLS fails	Use the mqtts:// endpoint and confirm the broker certificate is valid.
A publish succeeds but nothing replies	Confirm the outbound subscription and the hub authentication completed before sending. A broker acknowledgement alone does not confirm hub authentication or an application reply.
A reconnect fails authentication	Keep the SDK’s saved keys, check the hub password, and authenticate again before sending.
Messages are ignored	Publish to <topic_prefix>/in and subscribe to <topic_prefix>/out. Do not invent topic paths.

Tip

If WSS works and the client does not need a broker, keep using WSS.