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

# Kotlin SDK - Configuration

> NexusConfig and WifConfig field reference for the Kotlin SDK.

`NexusConfig` is the single configuration object passed to `NexusClient.create()`. All fields are immutable after construction.

## NexusConfig

```kotlin theme={null}
data class NexusConfig(
    val baseUrl:  String,
    val apiKey:   String?       = null,
    val ttl:      Duration      = 60.seconds,
    val wif:      WifConfig?    = null,
    val observer: NexusObserver = NoopNexusObserver,
)
```

### Field reference

| Field                  | Type            | Default             | Description                                                                                                                                                                                                                                                                         |
| ---------------------- | --------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`              | `String`        | -                   | Base URL of your Westyx Nexus service, for example `https://my-service.westyx.dev`. Trailing slash is stripped automatically.                                                                                                                                                       |
| `apiKey`               | `String?`       | `null`              | Service API key. Use a `wxs_...` key for backend services. Use `wxp_...` only for frontend/browser contexts where secrets must not be accessible. Mutually exclusive with WIF in practice - if WIF is enabled, the session token takes precedence over `apiKey` for authentication. |
| `ttl`                  | `Duration`      | `60.seconds`        | How long a synced snapshot is considered fresh. After this duration, `ensureFresh()` triggers a background sync on the next getter call.                                                                                                                                            |
| `wif`                  | `WifConfig?`    | `null`              | Workload identity federation settings. When `wif.enabled = true`, the SDK exchanges a cloud-provider OIDC token for a short-lived Nexus session token at startup. See [Workload identity](workload-identity).                                                                       |
| `observer`             | `NexusObserver` | `NoopNexusObserver` | Callbacks for stream lifecycle and error events. The default no-op observer discards all events. See [Stream observer](stream-observer).                                                                                                                                            |
| `sseReconnectCooldown` | `IntArray?`     | `null`              | Schedule for reconnecting SSE after falling back to TTL polling due to max consecutive transport errors. Unit: **minutes**. `null` = default `[5, 10, 20, 40, 60]` min. Single-element = fixed interval. Multi-element = custom schedule (stays at last value).                     |

## TTL explanation

The `ttl` controls how stale the local in-memory snapshot can get before the SDK triggers a background refresh.

* On every getter call (`getString`, `getBoolean`, etc.), `ensureFresh()` checks whether `now - syncedAt < ttl`.
* If the snapshot is stale, a background coroutine calls `sync()`. The current call returns the stale value immediately - there is no blocking.
* The stream push path (`connectStream`) bypasses this completely: when a push event arrives, `sync()` runs regardless of TTL.

Recommended values:

| Scenario                                        | TTL                                                 |
| ----------------------------------------------- | --------------------------------------------------- |
| Production service with SSE stream active       | `60.seconds` or higher - stream covers freshness    |
| Batch job or short-lived worker                 | `10.seconds` - aggressive polling, no stream needed |
| High-frequency read path, config rarely changes | `300.seconds` - reduce API call rate                |

## WifConfig

```kotlin theme={null}
data class WifConfig(
    val enabled:     Boolean                    = false,
    val provider:    String                     = "auto",
    val audience:    String                     = "westyx-nexus",
    val tokenSource: (suspend () -> String?)?   = null,
)
```

| Field         | Type                       | Default          | Description                                                                                                                                |
| ------------- | -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`     | `Boolean`                  | `false`          | Must be `true` to activate WIF. When `false`, WIF is completely bypassed even if other fields are set.                                     |
| `provider`    | `String`                   | `"auto"`         | Cloud provider to fetch the OIDC token from. One of: `kubernetes`, `aws`, `gcp`, `azure`, `developer`, `auto`. `auto` tries each in order. |
| `audience`    | `String`                   | `"westyx-nexus"` | OIDC audience claim sent to the cloud metadata endpoint (GCP only). Must match the trust policy configured in your Nexus project.          |
| `tokenSource` | `(suspend () -> String?)?` | `null`           | Custom async token supplier. When set, overrides `provider` entirely. Return `null` to signal that no token is available.                  |

## Minimal configs

<CodeGroup>
  ```kotlin title="API key only" theme={null}
  val config = NexusConfig(
      baseUrl = "https://my-service.westyx.dev",
      apiKey  = System.getenv("NEXUS_API_KEY"),
  )
  ```

  ```kotlin title="WIF with auto-detection" theme={null}
  val config = NexusConfig(
      baseUrl = "https://my-service.westyx.dev",
      wif = WifConfig(enabled = true),
  )
  ```

  ```kotlin title="Custom TTL and observer" theme={null}
  val config = NexusConfig(
      baseUrl  = "https://my-service.westyx.dev",
      apiKey   = System.getenv("NEXUS_API_KEY"),
      ttl      = 30.seconds,
      observer = MyNexusObserver(),
  )
  ```
</CodeGroup>