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"))

Caution

On Linux and macOS, SDKs reject config files and raw JSON identity files that are readable or writable by group or other users. Use chmod 600 before loading local identity material.

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.

If you keep _identity.json on a laptop, workstation, or VM, restrict it before the SDK reads it:

chmod 600 _identity.json

Python, Node.js, Go, and Rust SDKs reject local identity files with group or world permissions on Linux and macOS. In containers, mount the file from a secret store with owner-only permissions.

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

Safe Handling

1. Create one identity per client. Avoid sharing one identity across unrelated apps or devices.
2. Store it as a secret. Use a secret store, protected environment, or private runtime volume.
3. Keep access narrow. Grant only the permissions that client needs.
4. Rotate on exposure. Recreate the client identity if a file or secret is copied to the wrong place.
5. Review stale clients. Connections can show identity review when a client has not reported presence for a long time.
6. Refresh after protocol changes. Create or download a fresh identity after enabling HTTPS or MQTT.

Stale Identity Review

The dashboard marks a connection for identity review when no presence has been seen for an extended period. Review means “confirm the device or runtime is still expected” before trusting the identity again.

When the dashboard recommends quarantine, use Quarantine identity to disable runtime access and remove the client manifests. Rotate or recreate the identity before restoring access.

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.

Tip

The identity says who the client is. Request context says what this request is doing right now.

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. Use SDK Origins for reviewed browser domains, and keep secrets on a backend.

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.