.NET SDK - Configuration

NexusConfig is an init-only record that holds every value required to construct a NexusClient.

new NexusConfig
{
    BaseUrl    = "https://<slug>.westyx.dev",  // required
    ApiKey     = "wxs_...",                // required
    Ttl        = TimeSpan.FromSeconds(60),     // optional, default 60s
    LoggerFactory = null,                      // optional, discards SDK output when null
    HttpClient = null,                         // optional, for tests
}

Field reference

Field	Type	Default	Description
`BaseUrl`	`string`	-	Full service URL, e.g. `https://<slug>.westyx.dev`. The slug embedded in the host is extracted automatically and injected as the `Host` header on every request (Double-Gate requirement).
`ApiKey`	`string?`	`null`	Raw API key - sent verbatim in `X-Nexus-API-Key`. Either `wxs_...` (full access) or `wxp_...` (public configs and flags only). Optional when `Wif.Enabled = true`.
`Ttl`	`TimeSpan?`	`60 s`	Local cache TTL. After this elapses, the next read triggers a one-shot background refresh while still serving the stale cache.
`LoggerFactory`	`ILoggerFactory?`	`null`	Diagnostic logger factory. `null` discards SDK output. Each subsystem gets its own category (`Westyx.Nexus.NexusClient`, `Westyx.Nexus.Stream`, `Westyx.Nexus.Wif`).
`HttpClient`	`HttpClient?`	`null`	Override the internal HTTP client used for `/sync` and `/token-exchange` (mostly for tests). Defaults to a fresh `HttpClient` with a 10-second timeout.
`StreamHandler`	`HttpMessageHandler?`	`null`	Override the handler used for the long-lived SSE stream client. The stream client is always kept separate from `HttpClient` so a short consumer timeout cannot truncate the stream.
`PooledConnectionLifetime`	`TimeSpan?`	`2 min`	How long a pooled connection may be reused before the SDK’s own `HttpClient` instances retire it, so an application-lifetime singleton still observes a DNS change. Ignored when `HttpClient` is supplied.
`Wif`	`WifConfig?`	`null`	Workload Identity Federation. When `Enabled = true`, the SDK obtains a workload credential, exchanges it for a session JWT and uses bearer auth instead of the API key. See Workload identity.
`Observer`	`IStreamObserver?`	`null`	Optional structured-callback observer for SSE lifecycle events. See Stream observer.
`SseReconnectCooldown`	`int[]?`	`[5,10,20,40,60]`	Reconnect schedule in minutes after the stream falls back to polling. Must be non-empty with every entry `>= 1`.
`StreamIdleTimeout`	`TimeSpan?`	`90 s`	How long the SSE stream may go without receiving anything before the SDK reconnects. Reset by every line received, keepalive comments included, and sized against the backend’s 30-second `: ping`. Must be positive. (v0.14.0)
`StreamConnectTimeout`	`TimeSpan?`	`10 s`	Bound on the whole SSE connect-to-headers phase, so a server that accepts the connection and sends nothing is caught. Applies even with a supplied `StreamHandler`. Must be positive. (v0.14.0)

Validation

A value that cannot be meant is rejected at construction with NexusConfigException, which carries the offending property in Option:

new NexusConfig { BaseUrl = url, ApiKey = key, Ttl = TimeSpan.Zero }
// NexusConfigException: NexusConfig.Ttl: must be positive, got 00:00:00.

new NexusConfig { BaseUrl = url, ApiKey = key, SseReconnectCooldown = [5, -5] }
// NexusConfigException: NexusConfig.SseReconnectCooldown: entry 1 must be at least 1 minute, got -5.

null selects the default on every optional field, so a default is always expressible without passing a value that means something else.

API key types

Prefix	Access	Sync response shape
`wxs_...`	All configs, all secrets, all flags	`configs`, `secrets`, and `flags` populated
`wxp_...`	All configs and all flags - the same set a secret key sees	`secrets` field is entirely absent from the response

Calling GetSecret(...) with a public key throws NexusPublicKeyException.

Where to keep the API key

Anywhere IConfiguration already reads - environment variables, Azure Key Vault, AWS Secrets Manager, your existing secrets pipeline. The SDK never logs the raw key.

ApiKey = builder.Configuration["Nexus:ApiKey"]!  // from appsettings.json or env

Logging a `NexusConfig`

NexusConfig.ApiKey and NexusOptions.ApiKey carry [JsonIgnore] and [IgnoreDataMember], so a configuration serialized through System.Text.Json or Newtonsoft.Json contains the base URL and not the key. Serilog’s destructuring operator honours neither. {@Config} walks public properties directly, so log a config as {Config}:

log.LogInformation("Nexus configured: {Config}", config);   // base URL, no key
log.LogInformation("Nexus configured: {@Config}", config);  // the key is in your log sink

The same applies to an options type of your own: a record prints its properties from the compiler-generated ToString(), so a secret bound into one reaches any log that prints it. Use a class for a type that holds a secret.

Choosing the TTL

The TTL is a tradeoff between staleness window and redundant network traffic. With SSE enabled, changes propagate in milliseconds regardless of the TTL - the TTL only matters as a safety net if the stream falls back.

Use case	Suggested TTL
Frequently-changing flags, latency-sensitive	30 s
Standard configs with SSE	60 s (default)
Stable production secrets	5 min
Boot-time only, never reread	1 hour

If SSE is connected, the SDK clamps the effective TTL to at least 60 s - there is no point polling more aggressively when the stream pushes events the moment they happen.

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

.NET SDK - Configuration

Field reference

Validation

API key types

Where to keep the API key

Logging a `NexusConfig`

Choosing the TTL

​Field reference

​Validation

​API key types

​Where to keep the API key

​Logging a NexusConfig

​Choosing the TTL

Field reference

Validation

API key types

Where to keep the API key

Logging a `NexusConfig`

Choosing the TTL