SYMPHONY_ADDRESS

The SYMPHONY_ADDRESS environment variable tells the SDK where to reach Symphony when the address embedded in an extension's token is not the right one. All four SDKs (Go, Python, Java, Rust) honor the variable identically.

When to use it

Every Symphony API key token has the hostname of the Symphony instance that issued it base32-encoded in its first segment. On startup, the SDK decodes that hostname, exchanges the token for an API key over HTTPS, and uses the JWT it receives to open a NATS connection. If the embedded hostname is not reachable from where the extension runs — or is reachable on a different scheme or port — both the HTTPS exchange and the NATS connect fail.

Set SYMPHONY_ADDRESS to override that hostname when any of the following applies:

• The token was issued inside Kubernetes and carries the cluster-internal service DNS name (e.g. symphony.symphony.svc.cluster.local), but the extension runs outside the cluster.
• Symphony has been re-fronted by a new load balancer, ingress, or DNS alias since the token was issued, and the embedded hostname no longer resolves.
• A development token issued against one host is being reused against another — for example through an SSH tunnel, a port forward, or a local proxy.
• Symphony is exposed over plain HTTP for development or integration testing and no TLS certificate is available.

Leave SYMPHONY_ADDRESS unset when the token's embedded hostname is already reachable — the variable is only consulted as an override. The token itself is not modified.

How to set it

SYMPHONY_ADDRESS accepts three forms. Use the simplest one that expresses what you need:

# 1. Bare hostname. The SDK uses HTTPS on the default port (443) and
#    re-derives the NATS address from the JWT using this host.
export SYMPHONY_ADDRESS=symphony.example.com

# 2. Host with port. Uses HTTPS on the given port for the API-key
#    fetch. The NATS port from the JWT is preserved unchanged.
export SYMPHONY_ADDRESS=symphony.example.com:8443

# 3. URL with explicit scheme. The scheme (http or https) and port
#    apply to the API-key fetch only. NATS keeps the JWT's scheme
#    and port; only the host is substituted.
export SYMPHONY_ADDRESS=http://localhost:8080
export SYMPHONY_ADDRESS=https://symphony.example.com:8443

Start the extension with the variable in its environment:

SYMPHONY_ADDRESS=symphony.example.com ./my-extension

Or in a Kubernetes pod spec, a systemd unit, a docker run flag, or application.properties (Java) — wherever the extension's environment is configured.

What each component overrides

The SDK parses the value once into three components — scheme, host, and optional port — and routes them to two distinct connection legs:

Component	HTTPS API-key fetch and web_address	NATS audience re-derivation
scheme	Used. Default https.	Not used. The JWT's NATS scheme is preserved.
host	Used.	Used. Replaces the host in the JWT's aud claim.
port	Used. Default per scheme (443 / 80).	Not used. The JWT's NATS port is preserved.

The split exists because NATS speaks its own protocol on its own port. A scheme or port supplied for the API-key fetch has no meaning on the NATS leg, so an http://host:8080 override sends the API-key fetch to http://host:8080/api/v1/apikey and the NATS connection to <jwt-scheme>://host:<jwt-port>, not to port 8080.

For Go, Python, and Rust, the override also flows into the WebSocket-fallback URL: wss://... when the resolved scheme is https, ws://... when it is http. The Java SDK does not use a WebSocket fallback.

For Java specifically, the override is honored across all three startup paths: the constructor, REGISTRATION_TOKEN provisioning, and the provisioning reconnect that follows it.

Security considerations

TLS verification (https scheme)

When the resolved scheme is https, the SDK performs TLS verification against the server certificate. The value supplied for SYMPHONY_ADDRESS must match a Subject Alternative Name (SAN) on the certificate. Setting it to a bare IP address typically fails:

Could not contact Symphony at https://20.80.171.207/api/v1/apikey:
No subject alternative names matching IP address 20.80.171.207 found

To resolve a SAN mismatch:

• Use a DNS name that the certificate's SAN list already covers, and ensure that name resolves to the Symphony instance from the extension's host.
• Or reissue the certificate with the IP added to its SAN list.

The SYMPHONY_TLS_CA environment variable supplies a custom CA bundle when Symphony is fronted by an internal CA — but SYMPHONY_TLS_CA cannot fix a SAN mismatch.

Plain HTTP (http scheme)

When the resolved scheme is http, the API-key fetch sends the bearer token in plain text. The SDK logs a startup warning that names the resolved address. Treat HTTP as a development-only affordance:

• Use it for local testing, isolated networks, or behind an SSH tunnel.
• Do not use it across an untrusted network.
• Do not use it in production.

The SYMPHONY_TLS_CA variable is ignored when the resolved scheme is http.

Validation rules

The SDK rejects malformed values at startup with a single, user-actionable error. Each rule applies in every SDK:

• The scheme must be http or https. Other schemes (ftp://, nats://, …) are rejected.
• The value must not include a path. http://example.com/api/v1/apikey is rejected; a single trailing slash (http://example.com/) is allowed.
• The value must not include a query string or a fragment.
• The value must not include user info (http://user:pw@example.com).
• The host portion must not be empty.

Leading and trailing whitespace is trimmed before parsing.

Related environment variables

Variable	Purpose
SYMPHONY_TOKEN	API token used when none is passed to the extension constructor. May carry a registration token; the SDK detects this and provisions a permanent key.
REGISTRATION_TOKEN	One-time provisioning token. The SDK exchanges it for a permanent API key and stores the result in the OS credential store.
SYMPHONY_TLS_CA	Path to a PEM file whose certificates are trusted for both the HTTPS API-key exchange and the NATS TLS connection. Use when Symphony is fronted by a private or internal CA. Ignored when the resolved scheme is http.
NATS_TLS_CA	Path to a CA certificate for the NATS TLS connection only. Overrides SYMPHONY_TLS_CA for NATS.

If a future need surfaces to override the NATS scheme or port — for example, an extension that must route NATS over an ingress on a non-standard port — a separate variable will be introduced. SYMPHONY_ADDRESS is intentionally scoped to the HTTPS leg plus the host portion of the NATS audience.