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

# Spring Boot SDK - Configuration

> nexus.* property reference for the Spring Boot SDK.

The starter is configured via Spring Boot properties under the `nexus.*` prefix.

<CodeGroup>
  ```yaml title="application.yml" theme={null}
  nexus:
    base-url: https://<slug>.westyx.dev   # required
    api-key:  wxs_...                 # required
    ttl:      60s                         # optional, default 60s
    stream:   true                        # optional, default true
  ```

  ```properties title="application.properties" theme={null}
  nexus.base-url=https://<slug>.westyx.dev
  nexus.api-key=wxs_...
  nexus.ttl=60s
  nexus.stream=true
  ```
</CodeGroup>

## Field reference

| Property                       | Type       | Required | Default        | Description                                                                                                                                                                                                                                                                                             |
| ------------------------------ | ---------- | -------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nexus.base-url`               | `String`   | yes      | -              | 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).                                                                                                                                         |
| `nexus.api-key`                | `String`   | yes\*    | -              | Raw `wxs_...` or `wxp_...` key. Sent verbatim in `X-Nexus-API-Key`. *(v0.2.0)* Optional when `nexus.wif.enabled = true`.                                                                                                                                                                                |
| `nexus.ttl`                    | `Duration` | no       | `60s`          | Local cache TTL. After this elapses, the next read triggers a one-shot background refresh while still serving the stale cache.                                                                                                                                                                          |
| `nexus.stream`                 | `boolean`  | no       | `true`         | Whether to start the SSE live-update stream automatically. Set to `false` to run in pure TTL-polling mode.                                                                                                                                                                                              |
| `nexus.sse-reconnect-cooldown` | `int[]`    | no       | `null`         | *(v0.6.0)* Schedule for reconnecting SSE after falling back to TTL polling. Unit: **minutes**. `null` = default `[5, 10, 20, 40, 60]` min. Single-element = fixed interval. Multi-element = custom schedule (stays at last value). In `application.properties`: `nexus.sse-reconnect-cooldown=5,10,30`. |
| `nexus.wif.enabled`            | `boolean`  | no       | `false`        | *(v0.2.0)* Activate Workload Identity Federation. See [Workload identity](workload-identity).                                                                                                                                                                                                           |
| `nexus.wif.provider`           | `String`   | no       | `auto`         | *(v0.2.0)* One of `kubernetes`, `aws`, `gcp`, `azure`, or `auto`.                                                                                                                                                                                                                                       |
| `nexus.wif.audience`           | `String`   | no       | `westyx-nexus` | *(v0.2.0)* Audience claim requested from cloud IMDS.                                                                                                                                                                                                                                                    |

The starter accepts the standard Spring Boot duration suffixes - `s`, `ms`, `m`, `h`. `ttl: 60s` and `ttl: PT60S` are equivalent.

### Stream observer bean

*(v0.2.0)* The auto-configuration also picks up any `NexusStreamObserver` bean automatically - see [Stream observer](stream-observer) for the bean wiring pattern.

### `WIFConfig` bean

*(v0.2.0)* For custom token sources or test fixtures, define a `WIFConfig` bean - the auto-configuration uses it in preference to the `nexus.wif.*` properties. See [Workload identity](workload-identity).

## API key types

| Prefix    | Access                                                | Sync response shape                                      |
| --------- | ----------------------------------------------------- | -------------------------------------------------------- |
| `wxs_...` | Full - all configs, 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 `getSecret(...)` with a public key throws `NexusPublicKeyException` synchronously, before the network call.
</Warning>

## Where to keep the API key

Anywhere Spring Boot's `IConfiguration` already reads - environment variables, AWS Secrets Manager, HashiCorp Vault, your existing pipeline:

```yaml theme={null}
nexus:
  api-key: ${NEXUS_API_KEY}
```

Combined with profile-based config:

```yaml theme={null}
# application-prod.yml
nexus:
  base-url: https://prod-slug.westyx.dev
  api-key:  ${NEXUS_API_KEY}
```

The SDK never logs the raw key. Log lines reference key type only:

```
nexus: client ready (key_type=sk, ttl=PT1M)
```

## 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 when the stream falls back.

| Use case                                     | Suggested `nexus.ttl` |
| -------------------------------------------- | --------------------- |
| Frequently-changing flags, latency-sensitive | `30s`                 |
| Standard configs with SSE                    | `60s` (default)       |
| Stable production secrets                    | `5m`                  |
| Boot-time only, rarely re-checked            | `1h`                  |

## Disabling SSE

```yaml theme={null}
nexus:
  stream: false
```

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

## Customizing via `NexusConfig.Builder`

If you need to override more than the four properties (for example, inject a custom `HttpClient` for a corporate proxy), register a `NexusClient` bean of your own - the auto-configuration will back off:

```java theme={null}
@Configuration
public class NexusOverride {

    @Bean
    public NexusClient nexusClient() {
        HttpClient httpClient = HttpClient.newBuilder()
                .proxy(ProxySelector.of(InetSocketAddress.createUnresolved("proxy.corp.com", 8080)))
                .build();

        NexusClient client = NexusClient.create(NexusConfig.builder()
                .baseUrl(env.getProperty("nexus.base-url"))
                .apiKey(env.getProperty("nexus.api-key"))
                .httpClient(httpClient)
                .build());
        client.connectStream();
        return client;
    }
}
```

The `@ConditionalOnMissingBean` on the auto-configuration ensures the starter doesn't try to create its own bean when yours is present.