Hub Endpoints

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.

Each runtime transport completes v3 Noise before application traffic. An open socket, HTTP admission response, or broker connection alone is insufficient. Keep the client static key and verified server pins 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.

The SDK opens an HTTP admission, performs Noise, 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 retain replica cookies, manage polling, and close its admission 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 producing a fresh handshake. 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
  }
}

Troubleshooting

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 permissions.
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 admission succeeds but the handshake times out	Check for another process using the same identity and for lost replica affinity.
Requests reach the wrong route	Check `data_plane_endpoints` first, then `default_path`.

Last reviewed: September 9, 2026. Review this page when endpoint selection, supported SDK transports, HTTP admission, browser origins, or Noise readiness changes.