# Ask AI provider key

Source: https://docs.settlemint.com/docs/deployment/install/ask-ai-provider-key
Turn on Ask AI with an OpenRouter key or keep it off, limit questions per reader, also behind Cloudflare, and read the logs of a failed answer.

Ask AI answers questions in the documentation once the documentation pod holds an OpenRouter API key. This page covers supplying or disabling that key in the `dalp` Helm chart, configuring per-reader rate limits, applying cluster-level Envoy Gateway resources behind Cloudflare, and diagnosing failed answers. See [Configure values and secrets](https://docs.settlemint.com/docs/deployment/install/values-secrets) for other Helm values.

## Ask AI provider key [#ask-ai-provider-key]

Ask AI is the question-and-answer chat on the documentation site served under `/docs` on the Console hostname. The browser sends each question to the documentation server, and only the server calls OpenRouter, so the API key never reaches the browser.

Each request sends the conversation and matching documentation passages to OpenRouter on a DeepSeek model chosen by DALP. The API key does not select the model. The investor documentation site has no Ask AI and receives no key.

### Share the Console assistant key or supply a separate key [#share-the-console-assistant-key-or-supply-a-separate-key]

The chart passes the key to the documentation pod as `OPENROUTER_API_KEY`, read from a Kubernetes Secret named by `docs.openRouter.existingSecret` and `docs.openRouter.existingSecretKeys.apiKey`.

By default, those fields point at the release's shared environment Secret and its `ASSISTANT_OPENROUTER_API_KEY` entry (rendered from `global.dalpApp.env`). Setting `global.dalpApp.env.ASSISTANT_OPENROUTER_API_KEY` from your secret store turns on both Ask AI and the Console assistant for organisations without their own key.

Use a separate key when another team funds or caps documentation traffic in its own OpenRouter account:

- **Existing Secret:** Create a Secret in the release namespace, point `docs.openRouter.existingSecret` at it, and set `docs.openRouter.existingSecretKeys.apiKey` to the entry holding the key.
- **Chart-rendered Secret:** Set `docs.openRouter.existingSecret` to `""` and supply `docs.openRouter.apiKey` at deploy time from your secret store. The chart renders a Secret (named `docs-openrouter-key` with default naming) using the entry name in `docs.openRouter.existingSecretKeys.apiKey`. Note that the Helm release record stores this value like any other secret in Helm values.

Validation rules enforced by `helm install` and `helm upgrade`:

- Setting both `docs.openRouter.existingSecret` and `docs.openRouter.apiKey` fails the render. Clear `existingSecret` to `""` whenever you pass `apiKey`.
- Setting `docs.openRouter.apiKey` while `docs.openRouter.existingSecretKeys.apiKey` is empty fails the render.
- Adding `OPENROUTER_API_KEY` directly in `docs.env` fails the render.

The documentation pod does not run `summon`, so a Conjur `secrets.yml` mapping never reaches it. Always supply the key through a Kubernetes Secret.

### Keep Ask AI off [#keep-ask-ai-off]

To keep Ask AI off while the Console assistant keeps its key, clear `docs.openRouter.existingSecret` and leave `docs.openRouter.apiKey` empty:

```yaml
docs:
  openRouter:
    existingSecret: ""
```

With no key, an empty key, or a missing Secret entry, the pod starts normally, `/docs/api/chat` returns `404`, Ask AI entry points stay hidden, and built-in documentation search continues working without contacting OpenRouter.

### Verify the active state [#verify-the-active-state]

Check `/docs/api/chat-config` on the Console hostname:

```bash
curl -fsS https://console.example.com/docs/api/chat-config
```

The endpoint returns `{"enabled":true}` when the pod holds a key and `{"enabled":false}` when it does not. This confirms key presence only: an invalid OpenRouter key still reports enabled, and each question ends with "The answer could not be completed. Try again." Restart the documentation pods after changing a Secret unless your cluster restarts them automatically.

## Rate limits and trusted proxy [#rate-limits-and-trusted-proxy]

Anyone who can reach `/docs` can ask questions and spend OpenRouter credit. The documentation server admits up to 10 questions a minute per client and 300 an hour in total, distinguishing clients by the address your routing layer forwards.

When `global.dalpApp.env` defines `REDIS_URL`, documentation pods share rate-limit counters in Redis. Without Redis, each pod enforces its own 10-per-minute and 300-per-hour limits independently.

The chart derives `DOCS_CHAT_TRUSTED_PROXY` automatically (`envoy`, `nginx` or `openshift`) only when `docs.service.type` is `ClusterIP` and **exactly one** of `docs.ingress.enabled`, `docs.httpRoute.enabled` and `docs.openShiftRoute.enabled` is `true`. Otherwise it sets `none`, so all readers share one 10-questions-per-minute allowance. Because the default `dalp` chart enables both Ingress and HTTPRoute for `docs`, the default install uses `none`.

To override that derivation, set `DOCS_CHAT_TRUSTED_PROXY` in `docs.env` to `envoy`, `nginx` or `openshift`, and only when every public path to `/docs` passes through that proxy. Any other value causes Ask AI, search and Model Context Protocol requests to fail.

## Count readers separately behind Cloudflare [#count-readers-separately-behind-cloudflare]

These `ClientTrafficPolicy` and `EnvoyProxy` manifests belong in your **Envoy Gateway cluster configuration** (the namespace that owns your Gateway), not inside the `dalp` Helm release values.

Behind Cloudflare, Envoy Gateway sees a Cloudflare edge IP instead of each reader's IP, causing readers routed through the same Cloudflare address to share one budget. To count each reader separately, configure Envoy Gateway to trust the hop Cloudflare appends to `X-Forwarded-For`, keep that entry last, strip caller-supplied `x-envoy-external-address` headers, and restrict the load balancer to Cloudflare IP ranges.

### Set the `dalp` chart proxy profile [#set-the-dalp-chart-proxy-profile]

When `DOCS_CHAT_TRUSTED_PROXY` is `envoy`, the documentation server reads `x-envoy-external-address` first and falls back to the last entry of `X-Forwarded-For` when that header is absent or invalid. It never reads earlier entries, which callers can spoof.

To have the chart set `DOCS_CHAT_TRUSTED_PROXY=envoy` automatically, keep `docs.service.type: ClusterIP` and `docs.httpRoute.enabled: true`, and set `docs.ingress.enabled: false` and `docs.openShiftRoute.enabled: false`. Also set `global.dalpApp.config.trustedProxy.profile: envoy` so the Console, Investor portal and Platform API apply the same rule and record real client addresses in the audit trail.

### Apply Envoy Gateway policies to your Gateway [#apply-envoy-gateway-policies-to-your-gateway]

Cloudflare appends the reader's IP as the final entry of `X-Forwarded-For`. When Envoy Gateway enables `xForwardedFor`, it stops setting `x-envoy-external-address` (so an untrusted caller header would pass through) and appends Cloudflare's IP unless `disableXForwardedForAppend: true` is set (requires Envoy Gateway 1.9 or later).

Apply both `ClientTrafficPolicy` and `EnvoyProxy` together. If the load balancer still accepts direct connections from arbitrary IPs, callers can spoof `X-Forwarded-For` and bypass rate limits. Ensure no extra proxy sits between Cloudflare and your load balancer.

Add `clientIPDetection` and `headers.earlyRequestHeaders.remove` to the existing `ClientTrafficPolicy` targeting your Gateway (Envoy Gateway honours only the oldest policy per Gateway, and listener-scoped policies using `sectionName` override Gateway-wide ones). If none exists, create one:

```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: client-ip
  namespace: <gateway-namespace>
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: <gateway-name>
  clientIPDetection:
    xForwardedFor:
      numTrustedHops: 1
      disableXForwardedForAppend: true
  headers:
    earlyRequestHeaders:
      remove:
        - x-envoy-external-address
```

Restrict the load balancer `Service` in the `EnvoyProxy` referenced by your Gateway or GatewayClass (`parametersRef`). If other Gateways must remain reachable without Cloudflare, attach a dedicated `EnvoyProxy` to this Gateway. Compare the IPv4 and IPv6 ranges below against `https://www.cloudflare.com/ips-v4` and `https://www.cloudflare.com/ips-v6` before applying (published November 2026):

```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: <proxy-name>
  namespace: <gateway-namespace>
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
        externalTrafficPolicy: Local
        loadBalancerSourceRanges:
          - 173.245.48.0/20
          - 103.21.244.0/22
          - 103.22.200.0/22
          - 103.31.4.0/22
          - 141.101.64.0/18
          - 108.162.192.0/18
          - 190.93.240.0/20
          - 188.114.96.0/20
          - 197.234.240.0/22
          - 198.41.128.0/17
          - 162.158.0.0/15
          - 104.16.0.0/13
          - 104.24.0.0/14
          - 172.64.0.0/13
          - 131.0.72.0/22
          - 2400:cb00::/32
          - 2606:4700::/32
          - 2803:f800::/32
          - 2405:b500::/32
          - 2405:8100::/32
          - 2a06:98c0::/29
          - 2c0f:f248::/32
```

Verify that your cloud provider enforces `loadBalancerSourceRanges`, and block the Service's node ports from external traffic.

## Diagnose failed answers [#diagnose-failed-answers]

When an answer fails, read the documentation pod logs for `Ask AI provider call failed`:

| Field or `stage` value | Meaning | Next check |
| --- | --- | --- |
| `stage=no-response` | No HTTP response arrived from OpenRouter (`error_code` shows the network error). | Check DNS, egress rules and the host probe lines below. |
| `stage=first-chunk` or `between-chunks` | OpenRouter responded but sent no text in time. | Check OpenRouter status and outbound proxy buffering. |
| `stage=total` | The response ran past the 30-second total budget. | Check OpenRouter latency or retry. |
| `stage=response` | OpenRouter returned an HTTP error (`provider_status` holds the status, such as `401` or `429`). | Verify the API key (`401`) or OpenRouter account limits (`429`). |

After a `no-response` failure, the pod runs direct connectivity probes against `openrouter.ai` and logs `Ask AI provider host probe` within 20 seconds (info on success, error on failure):

- `stage=provider-host-lookup`: records whether `openrouter.ai` resolved.
- `stage=provider-host-connect` (`address_family` `ipv4` or `ipv6`): opens and immediately closes TCP port 443 to the first resolved address. Each line reports `elapsed_ms`, `timed_out` (`true` past 10 seconds) and `error_code` (`no_address` if that family has no record).

These probes connect directly and ignore pod HTTP proxy variables, so failed `provider-host-connect` lines are expected behind an outbound proxy. Without a proxy, failures on both families indicate blocked egress on port 443. A passing `ipv4` probe with a failing `ipv6` probe is normal because the HTTP client falls back to IPv4, though TLS or HTTP inspection can still block the call.

If logs show `Docs client address unavailable` when `DOCS_CHAT_TRUSTED_PROXY` is `envoy`, `nginx` or `openshift`, requests arrived without a usable forwarded IP and fell back to the shared rate-limit bucket. Inspect `envoy_external_address_present` and `forwarded_for_present` (`true` or `false`) and confirm every public route to `/docs` passes through the configured proxy (Envoy Gateway for `envoy`, NGINX Ingress for `nginx` or the OpenShift router for `openshift`).