Identity Files

An identity file is private setup material for one client. It tells the SDK how to authenticate, which protocols are enabled, and where to connect.

Create identities in Thalovant, then give each deployed client only the identity it needs.

Recommended Local Config

For local development, put SDK credentials in a protected YAML file:

install -d -m 700 ~/.config/thalovant
$EDITOR ~/.config/thalovant/config.yaml
chmod 600 ~/.config/thalovant/config.yaml

The SDKs read ~/.config/thalovant/config.yaml by default. If XDG_CONFIG_HOME is set, they read $XDG_CONFIG_HOME/thalovant/config.yaml. On Windows, they use %APPDATA%\Thalovant\config.yaml.

version: 1
profile: prod
profiles:
  prod:
    identity:
      access_key: client-access-key
      password: client-password
      crypto_key: optional-shared-key
      site_id: demo-agent
      default_master: https://jokes.thalovant.io
      default_port: 443
      default_path: /public
      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 }
      mqtt:
        endpoint: mqtts://mqtt.thalovant.com:8883
        username: client-access-key
        password: client-broker-password
        topic_prefix: hubs/hub-id/clients/client-id
        tls: true

You can add more profiles under profiles, then choose one in code.

SDK	Load default profile	Load named profile
Python	`ThalovantClient.from_config()`	`ThalovantClient.from_config(profile="prod")`
Node.js	`await ThalovantClient.fromConfig()`	`await ThalovantClient.fromConfig({ profile: "prod" })`
Go	`thalovant.NewClientFromConfig("", "")`	`thalovant.NewClientFromConfig("", "prod")`
Rust	`Client::from_config(None)`	`Client::from_config(Some("prod"))`

At A Glance

Field	Required	Purpose
`access_key`	Yes	Public identifier for the client.
`password`	Yes	Secret used by the client during auth.
`crypto_key`	Sometimes	Shared key when encrypted payloads are enabled.
`site_id`	Recommended	Stable client site, device, service, or runtime label.
`data_plane_endpoints`	Recommended	Explicit WSS, HTTPS, and MQTT addresses.
`protocols`	Recommended	Protocol availability for this hub.
`mqtt`	MQTT only	Per-client broker endpoint, username, password, and topic scope.

Raw Identity File

{
  "access_key": "client-access-key",
  "password": "client-password",
  "crypto_key": "optional-shared-key",
  "site_id": "demo-agent",
  "default_master": "https://jokes.thalovant.io",
  "default_port": 443,
  "default_path": "/public",
  "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 }
  },
  "mqtt": {
    "endpoint": "mqtts://mqtt.thalovant.com:8883",
    "username": "client-access-key",
    "password": "client-broker-password",
    "topic_prefix": "hubs/hub-id/clients/client-id",
    "tls": true
  }
}

Raw JSON identity files are still supported. Use them for downloaded single-client identities or mounted Kubernetes secrets. Use the YAML config when you want named local profiles.

The SDKs also support environment variables for container and CI usage. Prefer secret stores for production deployments.

Safe Handling

Create one identity per client. Avoid sharing one identity across unrelated apps or devices.
Store it as a secret. Use a secret store, protected environment, or private runtime volume.
Keep access narrow. Grant only the permissions that client needs.
Rotate on exposure. Recreate the client identity if a file or secret is copied to the wrong place.
Refresh after protocol changes. Create or download a fresh identity after enabling HTTPS or MQTT.

Client Metadata

Use site_id and request context together:

Metadata	Best use
`site_id`	Stable runtime, device, room, service, or deployment label.
`session_id`	Conversation, workflow, user journey, or trace group.
`request_id`	Single request trace through logs and support records.
Context	User, platform, app version, locale, or flow details.

Do Not Store

Public repos

Do not commit identity files, copied setup commands, or raw environment files.

Browser bundles

Do not ship long-lived client secrets in JavaScript served to users.

Logs

Redact passwords, access keys, crypto keys, broker passwords, and setup material before logging.

Support tickets

Share request IDs, hub names, and visible errors instead of setup material.