Hub Endpoints

Use WSS, HTTPS, and MQTT over TLS hub endpoints so SDK clients can connect without installing a desktop app.

View as Markdown Open in Claude Open in ChatGPT

A hub endpoint is the network address a client uses after Thalovant creates its identity.

Public hubs expose only the protocols enabled for that hub. WSS is the default public path. HTTPS and MQTT are optional.

Browser apps also need an approved SDK origin before calls from a customer-owned domain can pass the API CORS check.

At A Glance

Endpoint type	Best for
WSS	Realtime clients, event listeners, voice flows, and agents.
HTTPS	Polling sessions for CLIs, server jobs, health checks, and tests.
MQTT over TLS	Broker-mediated device, edge, or network-constrained traffic.
Same identity	All transports use the same client identity and access policy.

Python, Node.js, Go, and Rust support all three transports outside the browser. Kotlin, Swift, and .NET support WSS; embedded C supplies the protocol while the application owns its transport. Check Supported Versions before choosing a client.

Every transport is encrypted and authenticated before application traffic flows. An open socket, an HTTP response, or a broker connection alone is not a session. Keep the SDK’s saved keys across restarts, as described in Identity Files.

Identity Endpoint Fields

The SDKs prefer explicit data-plane endpoints when the identity includes them.

{
  "data_plane_endpoints": {
    "wss": "wss://jokes.thalovant.io/public",
    "https": "https://jokes.thalovant.io/public",
    "mqtt": "mqtts://mqtt.thalovant.com:8883"
  },
  "protocols": {
    "wss": { "enabled": true },
    "http": { "enabled": true },
    "mqtt": { "enabled": true }
  }
}

Older or minimal identities may use these fields:

Field	Meaning
`default_master`	Hub host or full HTTPS address.
`default_port`	Port to use when the host does not already include one.
`default_path`	Optional path prefix used by routed public hubs.

When To Use WSS

Choose WSS first when the client can keep a connection open.

Live agent

An agent keeps a session active and reacts to replies, policy events, or display updates.

Voice flow

A voice client sends utterances and listens for speech responses.

Event subscriber

A client listens for hub events and maps them into an app-specific state model.

When To Use HTTPS

Choose HTTPS when the client needs a direct answer and does not need a live socket.

Over HTTPS the SDK signs in, authenticates, sends encrypted messages, and polls for replies. It keeps a stateful hub session for that work; an ask is more than one HTTP request. Let the SDK keep its session cookies, manage polling, and close the session when the work finishes.

Use a separate identity for every independently active client. If another app already owns the same identity’s HTTP session, a new /connect can succeed without giving you a session of your own. Stop the owning client or provision a distinct identity before retrying.

Server task

A job sends one user request, reads the reply, and exits.

CLI

A developer or support tool sends diagnostics and prints the result.

Test client

A test checks auth, endpoint routing, and response parsing.

Browser Origin Checks

An approved SDK origin allows non-credentialed API CORS for one exact browser origin. It is separate from hub protocol support and the hub’s own origin and cookie handling. Direct HTTPS runtime sessions use cookies, so API-origin approval alone does not establish that a cross-origin hub session will work.

Use it for browser apps that need to call Thalovant from a reviewed domain. Do not use it to move identity files, broker passwords, setup links, refresh flows, or payment secrets into browser code.

When To Use MQTT

Choose MQTT when a broker makes the deployment simpler than direct hub traffic.

MQTT uses TLS and per-client credentials. A client identity must include the mqtt block before SDKs can use that transport.

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

If One Transport Fails

Symptom	Check first
WSS works but HTTPS fails	Confirm HTTPS is enabled for the hub.
HTTPS works but WSS fails	Confirm the public hub exposes the WebSocket route and TLS certificate.
MQTT is unsupported	Use Python, server-side Node.js, Go, or Rust, then confirm the hub and identity enable MQTT.
MQTT fails immediately	Check the identity’s MQTT block, broker credentials, TLS, and topic access rules.
Auth fails on every transport	Check the identity password and endpoint, restore persistent client state if it was lost, and verify any intended server-key rotation before changing pins.
HTTPS connects but authentication times out	Check for another process using the same identity, and that the client kept its session cookies.
Requests reach the wrong route	Check `data_plane_endpoints` first, then `default_path`.