# Topologies that work — and the cross-origin wall

URL: https://kywi-docs-production.up.railway.app/integrating/topologies-that-work--and-the-cross-origin-wall
Type: docPage

A decoupled frontend consumes the API server-side: core emits no CORS headers, so a browser on another origin is never a supported caller.

Kywi emits no CORS headers. Not on a preflight, not on a successful response, not on an error — no package in the monorepo sets an `Access-Control-*` header anywhere. So a decoupled frontend consumes the API *from its server*: a React app calling `fetch('https://cms.example.com/api/v1/content/page')` from the browser is not a configuration away from working, it is outside the supported set.

## What the failure actually looks like

Not a 403, which is what makes it confusing to debug. The preflight succeeds and the real request succeeds; the browser throws the answer away because no header authorized it to be read.

$ curl -i -X OPTIONS -H 'Origin: https://app.example.com' \ https://cms.example.com/api/v1/content/page HTTP/1.1 204 No Content allow: DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT # …and no access-control-allow-origin

Kywi's own middleware does see this request — its matcher covers every `/api/v1/*` path with no method check, so a preflight reaches it exactly as a GET would. But its job there is narrow: bridge a session cookie into an `Authorization` header, then step aside. It sets no `Access-Control-*` header on anything, preflight included. From there Next answers the `OPTIONS` itself — the scaffolded API route exports the five verbs and no `OPTIONS` handler, so Next synthesizes the response — and core's router, which also registers only those same five verbs, never runs at all. In the browser you get a CORS error with no server-side trace: the access log shows two clean responses.

## Runtime writes reject cross-origin deliberately

The two visitor-facing write routes — `POST /kywi/audience` and `POST /kywi/self-id` — do not merely lack CORS, they check where the request came from and refuse. The check reads `Origin` first, falls back to `Sec-Fetch-Site`, then to a same-origin `Referer`. Evidence of a different origin fails, and so does *no evidence at all*: a curl or a server-side script with none of the three headers is treated as a forged submit.

## POST /api/v1/kywi/audience — Origin: https://elsewhere.example

If the site issues a `kywi_csrf` cookie, those routes additionally require a matching `X-CSRF-Token` header (or a `_csrf` form field). A site that issues no such cookie is protected by the origin evidence alone.

## The four topologies that work

**Coupled.** One Next app renders the public site and serves the API and admin. Every call is same-origin and none of this applies.

**Headless or decoupled with a server-side consumer.** Your frontend's server holds an API key and calls `/api/v1`; the browser only ever talks to your frontend. This is what "decoupled" means in Kywi, and it is the reason the credential model is a bearer key rather than a cookie — see [Authenticating an external caller](/integrating/authenticating-an-external-caller/).

**Browser code on a Kywi-rendered page.** `@kywi-software/js` is same-origin by construction: it boots from the page it was rendered into, derives its API base from that page's own base path, and picks up the CSRF token the page rendered. It is not a client you can point at a remote Kywi — see [The browser runtime](/integrating/the-browser-runtime-kywi-js/).

**A reverse proxy that rewrites Host.** Serving `example.com/cms/…` from a Kywi behind it makes the calls same-origin for real, which is the only thing that removes the wall.

## A proxy must rewrite Host, not just forward it

The API resolves which site a request is for from the `Host` header, and `X-Forwarded-Host` is deliberately not read — honouring it would let the API resolve a different site than the page that called it. A proxy that passes its own hostname through does not error: the Host matches no configured site, so every request quietly resolves to the first site in `sites[]`. On a single-site install you will never notice; on a multi-site one you will serve the wrong site's content. See [Site scoping and the `?siteId=` contract](/integrating/site-scoping-and-the-siteid-contract/).

## What a server-side consumer can still do

Everything, including targeting. Personalization is resolved server-side in Kywi anyway — losing arms are pruned before the HTML leaves — so a non-Kywi frontend drives audiences and experiments through the same server-side calls rather than through browser JavaScript. See [Personalization and experiments from a non-Kywi frontend](/integrating/personalization-and-experiments-from-a-non-kywi-frontend/) for the shape of that, and [The three deployment modes](/integrating/the-three-deployment-modes/) for what "decoupled" changes in the project itself, which is less than most people expect.
