[Proposal] Approach for attaching backend/upstream security across RestApi, LlmProvider, LlmProxy, and Mcp

[Thenujan-Nagaratnam]

Why we need this

RestApi has no dedicated field for upstream/backend authentication today — the only way to get any auth-like effect is to manually attach a generic policy (e.g. set-headers) via the policies: list and scope it by hand, with no structural guarantee it stays scoped to the right backend. LlmProvider, LlmProxy, and Mcp each already have their own dedicated auth field, but they aren't consistent with each other (see below), and RestApi is now gaining per-operation, multi-backend routing (multiple named upstreamDefinitions, picked per operation), which makes "how do we attach credentials to a specific backend safely" a real gap to close rather than a nice-to-have.

The core question this discussion is trying to answer: should backend/upstream auth be a first-class thing in the API definition — a dedicated auth field, as LlmProvider/LlmProxy/Mcp already have — or should it stay something achieved indirectly through the existing generic policies: mechanism, with no dedicated field at all? The options below split along this line: A/B/C make it first-class (in different shapes); D/E keep it policy-only.

Current state

	RestApi	LlmProvider	LlmProxy	Mcp
Auth field exists?	No	Yes (spec.upstream.auth)	Yes (provider.auth + additionalProviders[].auth)	Yes (spec.upstream.auth)
Method used to add it today	No dedicated mechanism — the only way to get any auth-like effect is to manually attach a generic policy (e.g. set-headers) via the policies: list and scope it by hand	Dedicated auth sub-field directly on spec.upstream	Dedicated auth sub-field on provider and on each additionalProviders[] entry	Dedicated auth sub-field directly on spec.upstream
Type enum enforced?	n/a	Yes	Yes	No — any string passes validation
Policy attached	n/a	set-headers	set-headers	set-headers

Example configs

To ground the discussion, here's what a config looks like for each kind with the proposed auth field (shown in the Option B shape below) added where it's new.

RestApi — auth attaches to a named backend in the upstreamDefinitions pool, and operations pick which backend (and therefore which auth) they use by referencing it:

apiVersion: gateway.api-platform.wso2.com/v1
kind: RestApi
metadata:
  name: shop-api-v1.0
spec:
  displayName: Shop API
  version: v1.0
  context: /shop/$version
  upstreamDefinitions:
    - name: user-service
      upstreams:
        - url: http://user-service:8080
      auth:
        type: api-key
        version: v1
        params:
          header: Authorization
          value: Bearer user-service-token
    - name: promo-service
      upstreams:
        - url: http://promo-service:8080
      # no auth needed for this one
  upstream:
    main:
      url: http://default-backend:8080
  operations:
    - method: GET
      path: /products
      # falls back to the API-level default-backend (no auth)
    - method: GET
      path: /users/{id}
      upstream:
        main:
          ref: user-service   # picks up user-service's auth

LlmProvider / Mcp — typically a single upstream, so auth applies unconditionally in the common case:

apiVersion: gateway.api-platform.wso2.com/v1
kind: LlmProvider
metadata:
  name: openai-provider
spec:
  displayName: OpenAI Provider
  version: v1.0
  template: openai
  upstream:
    url: https://api.openai.com/v1
    auth:
      type: api-key
      version: v1
      params:
        header: Authorization
        value: Bearer sk-live-...
  accessControl:
    mode: allow_all

LlmProxy — auth on the primary provider and on each additional provider, applied depending on which one is selected for a given request:

apiVersion: gateway.api-platform.wso2.com/v1
kind: LlmProxy
metadata:
  name: multi-model-proxy
spec:
  displayName: Multi-Model Proxy
  version: v1.0
  provider:
    id: openai-provider
    auth:
      type: api-key
      version: v1
      params:
        header: Authorization
        value: Bearer sk-live-openai
  additionalProviders:
    - id: anthropic-provider
      as: anthropic-upstream
      auth:
        type: api-key
        version: v1
        params:
          header: x-api-key
          value: sk-ant-...

Options

Options A, B, and C make auth first-class — a dedicated auth field, in different shapes. Options D and E don't — auth stays something you attach as a regular policy, with no dedicated field.

Option A — Typed shape: { type, header, value }

auth:
  type: api-key
  header: Authorization
  value: Bearer <token>

The existing LlmProvider/Mcp shape, extended with more fields as new auth mechanisms are added (e.g. clientId, clientSecret, tokenUrl for OAuth2).

Pros: minimal change from what exists today; self-documenting in the schema.
Cons: doesn't scale — every new mechanism needs new fields and new gateway-controller code; params validation has to live in the gateway.

Option B — Policy-reference model: { type, name, version, params }

auth:
  type: api-key        # or basic / oauth2 / other
  version: v1
  params:
    header: Authorization
    value: Bearer <token>

auth:
  type: other
  name: upstream-oauth2-authentication
  version: v1
  params:
    clientId: ...
    clientSecret: ...
    tokenUrl: ...
    grantType: client_credentials

api-key/basic/oauth2 are shorthand for well-known built-in policies. other references any policy by name/version directly. version is always required, for every type. params is passed through to the resolved policy unexamined — validated by that policy's own schema, not by the gateway.

Pros: one shape reused across all four kinds; new auth mechanisms need no schema change, just a new policy definition; gateway never needs to know what a valid oauth2/custom config looks like.
Cons: less self-documenting than Option A (the schema doesn't describe what oauth2/custom params look like); a typo in name/version only fails at validation time.

Option C — Fully generic: { name, version, params }, no predefined types

auth:
  name: upstream-auth-apikey
  version: v1
  params:
    header: Authorization
    value: Bearer <token>

Even api-key/basic become "just another named policy" — no type shorthand at all.

Pros: simplest possible schema; zero special-casing in gateway-controller for any mechanism.
Cons: worse ergonomics for the common case — every config needs to know an exact policy name and version; no fixed enum to drive a console/UI picker.

Option D — No dedicated field; rely on the generic policies list

Don't add a schema field at all — attach a normal policy (e.g. set-headers) via the existing policies: list and scope it by hand. This is what's already possible today for RestApi.

Pros: no new schema surface.
Cons: no structural guarantee that a manually-attached policy only applies to the backend it was meant for; poor discoverability — an auth policy looks like any other policy in the list.

Option E — Leave the existing auth fields as they are; add anything new as a policy

Don't change LlmProvider/LlmProxy/Mcp's current auth shape at all — it keeps working exactly as it does today, with no migration or compatibility work needed for existing configs. For RestApi (which has no auth today) and for any future auth mechanism, don't extend a typed auth field — attach it as a normal policy via the existing policies: list instead.

Pros: zero migration risk for the three kinds that already have a working auth field, since nothing about them changes; no new schema surface needed for RestApi either.
Cons: doesn't reconcile the differences between how LlmProvider/LlmProxy/Mcp each already validate/enforce auth; RestApi's auth would have the same scoping-safety gap as Option D.

Where we're leaning, and what we'd like feedback on

The first question we need to settle is the core one above: first-class field, or policy-only? We're currently leaning towards making it first-class, via Option B: it keeps a simple, discoverable shape for the common cases (api-key/basic/oauth2) while making new or custom auth mechanisms a policy-registry concern rather than a recurring schema change, and lets us use one shared mechanism across all four kinds instead of four separate ones.

That said, this is genuinely open — we'd like feedback on whether first-class is the right call at all, and if so, whether B is the right shape for it. In particular:

1. Should auth be first-class at all, or is Option D/E's policy-only approach the better call? Both need no (or minimal) schema change and reuse infrastructure that already exists. Their downside (no structural guarantee that a manually-attached policy stays scoped to the right backend) may or may not be a dealbreaker depending on how much we value discoverability vs. minimizing new surface area and migration risk.
2. If first-class, whether the api-key/basic/oauth2 shorthand in Option B is worth the added schema complexity over the fully generic Option C.
3. If first-class, whether auth should be reachable from a single top-level upstream slot (as it is for LlmProvider/Mcp today) or only from named upstreamDefinitions entries.
4. Any mechanism/use case these options don't cover.