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

# Python SDK - Configuration

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

`NexusConfig` is a frozen `dataclass` holding every value required to construct a client. Pass it to `NexusClient.create()` or `AsyncNexusClient.create()` (both accept the same instance).

```python theme={null}
from westyx_nexus import NexusConfig

config = NexusConfig(
    base_url        = "https://<slug>.westyx.dev",  # required
    api_key         = "wxs_...",                # required
    ttl_seconds     = 60.0,                         # optional, default 60s
    timeout_seconds = 10.0,                         # optional, default 10s
    stream          = True,                         # optional, default True
    logger          = None,                         # optional
)
```

## Field reference

| Field                    | Type                       | Default | Description                                                                                                                                                                                                             |
| ------------------------ | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_url`               | `str`                      | -       | Full service URL, e.g. `https://<slug>.westyx.dev`. The slug embedded in the host is also used as the `Host` header on every request (Double-Gate requirement).                                                         |
| `api_key`                | `str`                      | `""`    | Raw `wxs_...` or `wxp_...` key. Sent verbatim in `X-Nexus-API-Key`. Optional when `wif` is enabled.                                                                                                                     |
| `ttl_seconds`            | `float \| None`            | `60.0`  | Local cache TTL. After this elapses, the next read triggers a one-shot background refresh while still serving the stale cache.                                                                                          |
| `timeout_seconds`        | `float`                    | `10.0`  | Per-request HTTP timeout in seconds. *(v0.2.0)* Applies only to the `/sync` and `/token-exchange` client - the SSE stream uses a separate client with `timeout=None`, so a short value here cannot truncate the stream. |
| `stream`                 | `bool`                     | `True`  | Whether to start the SSE live-update stream automatically. Set to `False` to run in pure TTL-polling mode.                                                                                                              |
| `logger`                 | `NexusLogger \| None`      | `None`  | Optional logger; `None` discards SDK output. See Custom logging.                                                                                                                                                        |
| `wif`                    | `WIFConfig \| None`        | `None`  | *(v0.2.0)* 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).                |
| `stream_observer`        | `StreamObserver \| None`   | `None`  | *(v0.2.0)* Optional structured-callback observer for SSE lifecycle events. See [Stream observer](stream-observer).                                                                                                      |
| `sse_reconnect_cooldown` | `int \| list[int] \| None` | `None`  | Schedule for reconnecting SSE after falling back to TTL polling. Unit: **minutes**. `None` = default `[5, 10, 20, 40, 60]` min. `int` = fixed interval. `list[int]` = custom schedule (stays at last value).            |

## API key types

| Prefix    | Access                                              | Sync response shape                                      |
| --------- | --------------------------------------------------- | -------------------------------------------------------- |
| `wxs_...` | Full - all configs, all secrets, all flags          | `configs`, `secrets`, and `flags` populated              |
| `wxp_...` | Restricted - server-filtered configs and flags only | `secrets` field is **entirely absent** from the response |

<Warning>
  Calling `get_secret(...)` with a public key raises `NexusPublicKeyError` synchronously, before the network call.
</Warning>

## Where to keep the API key

Anywhere your existing config pipeline puts secrets - environment variables, AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or a local `.env` file in dev. The SDK never logs the raw key.

```python theme={null}
import os
config = NexusConfig(
    base_url=os.environ["NEXUS_URL"],
    api_key=os.environ["NEXUS_API_KEY"],
)
```

For Pydantic / pydantic-settings users:

```python theme={null}
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    nexus_url: str
    nexus_api_key: str

settings = Settings()
config = NexusConfig(base_url=settings.nexus_url, api_key=settings.nexus_api_key)
```

## Choosing the TTL

The TTL is a tradeoff between staleness window and redundant network traffic. With SSE enabled (default), **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_seconds` |
| -------------------------------------------- | ----------------------- |
| Frequently-changing flags, latency-sensitive | 30.0                    |
| Standard configs with SSE                    | 60.0 (default)          |
| Stable production secrets                    | 300.0 (5 min)           |
| Boot-time only, never rechecked              | 3600.0 (1 hour)         |

## Disabling SSE

```python theme={null}
config = NexusConfig(
    base_url="...",
    api_key="...",
    stream=False,   # SSE off; use TTL polling only
)
```

Useful in environments where outbound long-lived connections are blocked (some serverless platforms, certain corporate proxies).