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
      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: <namespace>/<hub-id>/<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.
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.

Hubs no longer issue a crypto_key. Encryption comes from the SDK’s own authenticated session, keyed from the identity’s password. Current SDKs accept and ignore crypto_key in older identity files. The identity still needs a valid password and an enabled endpoint.

Raw Identity File

{
  "access_key": "client-access-key",
  "password": "client-password",
  "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": "<namespace>/<hub-id>/<client-id>",
    "tls": true
  }
}

Raw JSON identity files are still supported. Use them for downloaded single-client identities or securely mounted credential files. 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 access rules 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.

Saved Keys

The identity file and the SDK’s saved keys work together. Keep both across application and container restarts:

Material	Why it must survive
Client key	The hub recognises this client by it after the first connection. Replacing it on every start makes the client a stranger each time.
Recorded hub identities	The SDK uses these to recognise the hub on reconnect and to reject an unexpected one.
Cached credentials, when used	These save deriving from the password on every connection. Protect them like the password.

Use a private, writable, persistent directory or the SDK’s platform storage provider. An identity file mounted read-only is useful for credentials, but the SDK also needs writable storage for its own saved keys. A custom identity-file path does not by itself relocate that state. Language-specific directory options and platform requirements are listed on the SDK pages.

For server-side Node and MCP, the saved keys live next to the config file: ~/.config/thalovant by default, $XDG_CONFIG_HOME/thalovant when that variable is set, or %APPDATA%\Thalovant on Windows. Preserve the directory as a unit. MCP has no per-tool option for it.

Node writes its saved keys atomically across processes. Damaged saved keys stop the operation without resetting what was saved. If a crashed process leaves .noise-state.lock behind, confirm the process has stopped before removing only the lock file, and keep the key files. This lock does not coordinate live hub sessions or browser tabs.

Damaged saved hub identities stop authentication without overwriting the original state. For SDKs that store them as hexadecimal, upper- and lowercase encodings of the same key identify the same hub.

A failed connection is not a reason to delete saved keys or generate new ones. Check the identity password, the endpoint, and that the original client key is available. Confirm a changed hub identity with the hub owner before accepting it.

Safe Handling

1. Create one identity per active client process. Give parallel services, MCP processes, and devices separate identities. HTTP and MQTT sessions use identity-scoped state, so sharing credentials can make clients consume or close each other’s session.
2. Store it as a secret. Use a secret store, protected environment, or private runtime volume.
3. Keep access narrow. Grant only the access rules 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 that client’s access. 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.