Skip to content

Topologies that work — and the cross-origin wall

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.

bash
$ 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.examplejson
{"error":{"code":"FORBIDDEN","message":"Cross-origin request rejected"}}

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.

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.

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.

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 for the shape of that, and The three deployment modes for what "decoupled" changes in the project itself, which is less than most people expect.