> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET SDK - Configuration

> NexusConfig field reference and TTL guidance for the .NET SDK.

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

```csharp theme={null}
new NexusConfig
{
    BaseUrl    = "https://<slug>.westyx.dev",  // required
    ApiKey     = "wxs_...",                // required
    Ttl        = TimeSpan.FromSeconds(60),     // optional, default 60s
    Logger     = null,                         // optional, see Custom logging
    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.                                                                                                |
| `Logger`               | `INexusLogger?`       | `null`  | Diagnostic logger. `null` discards SDK output. See Custom logging.                                                                                                                                                            |
| `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.                                       |
| `Wif`                  | `WIFConfig?`          | `null`  | Workload Identity Federation. When `Enabled = true`, the SDK exchanges an OIDC token for a session JWT and uses bearer auth instead of the API key. See [Workload identity](workload-identity).                               |
| `Observer`             | `IStreamObserver?`    | `null`  | Optional structured-callback observer for SSE lifecycle events. See [Stream observer](stream-observer).                                                                                                                       |
| `SseReconnectCooldown` | `int[]?`              | `null`  | Schedule for reconnecting SSE after falling back to TTL polling. Unit: **minutes**. `null` = default `[5, 10, 20, 40, 60]` min. Single-element array = fixed interval. Multi-element = custom schedule (stays at last value). |

## API key types

| Prefix    | Access                                                                 | Sync response shape                                      |
| --------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
| `wxs_...` | Full - all configs (regardless of `is_public`), all secrets, all flags | `configs`, `secrets`, and `flags` populated              |
| `wxp_...` | Restricted - only `is_public: true` configs and flags                  | `secrets` field is **entirely absent** from the response |

<Warning>
  Calling `GetSecretAsync(...)` with a public key throws `NexusPublicKeyException` synchronously, before the network call.
</Warning>

## 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.

```csharp theme={null}
ApiKey = builder.Configuration["Nexus:ApiKey"]!  // from appsettings.json or env
```

## 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         |

<Info>
  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.
</Info>