Skip to content

Site scoping and the ?siteId= contract

Site resolution runs `?siteId=` first, then a Host match against the configured domains, then `sites[0]` — and most routes take a slug or the DB UUID.

Every site-scoped route answers for exactly one site, and works out which one the same way: an explicit ?siteId=, else a match of the request's Host against the domains and aliases in sites[], else the first configured site. There is no fourth step and no error step — the fallback always succeeds.

The three steps of site resolution, in order. The first that produces a configured site wins.
NameTypeDefaultDescription
?siteId=config slug or DB UUIDchecked first
The site id from kywi.config.ts (default, docs), or the UUID GET /sites returns — the admin site switcher sends the latter. A value that matches neither is ignored and resolution continues to the next step.
Host headera configured domain or aliaschecked second
Hostname and port both, which is what makes docs.localhost:3000 select a second site with no DNS. Never the request URL, and never X-Forwarded-Host.
sites[0]—the fallback
The first entry in sites[]. Reached whenever the other two say nothing — including an unrecognized ?siteId= and an unparseable Host.

Why the Host header and not the URL

Inside a Next Route Handler, request.url carries the server's own bound origin, not the host the client asked for. Matching on it pinned every hostname to the first site, which is why resolution reads the Host header instead. The query string still comes from the URL, so an explicit ?siteId= works even when the Host is malformed.

X-Forwarded-Host is deliberately ignored: honouring it would let the API resolve a different site than the page that made the call. A proxy must rewrite Host, as it already must for the render path. The Host is client-controllable, but it can only select among sites the operator already declared — it grants nothing.

Slug or UUID, both accepted

Most routes take either spelling. Internally a route that needs a UUID resolves a slug with one lookup and passes a UUID straight through, so a caller can hard-code the readable id from kywi.config.ts and never touch GET /sites.

GET/api/v1/content/page?siteId=docsNo auth

siteId=docs and siteId=1821c45b-27fa-4b9f-b70e-659650711133 resolve to the same site. Rows carry the resolved UUID in their own siteId field — the quickest confirmation that you addressed the site you meant. The anonymous 200 shown here is specific to the default page content type: every GET /content/:type call is still gated by that type's own access configuration, checked before site resolution even runs, so a type configured for editor-only reads answers 401 to the identical call.

Selecting a site is not permission to act on it

Roles are global — a siteAdmin is a siteAdmin everywhere — so every site-scoped route runs a per-site access check on the resolved id. Under the default policy a user with no membership rows is unrestricted, which is what keeps single-site installs working, and a user with any rows is confined to exactly those sites. strictSiteMembership flips that: no rows means no access, so removing someone's last membership narrows their reach to nothing instead of widening it to everything. A refusal is a 403 — You do not have access to this site.

Two seams that do not follow the precedence

Changesets take a raw value. The changeset routes read body.siteId on create and ?siteId= on every read, and use it as-is: no slug resolution, no Host match, no fallback beyond the install default. Because kywi_changesets.site_id is a plain text column, creating a changeset with {"siteId": "docs"} appears to succeed, and then every read of that changeset fails when the stored slug is compared against content's uuid column. Pass the DB UUID from GET /sites to changeset routes, always. See Batching and publishing with changesets.

GraphQL will not infer the site at all. Every siteId argument in the schema is non-null, so a query that omits it is rejected before any resolver runs — the Host fallback that exists in the resolver is unreachable over HTTP. There is no "current site" in GraphQL; you name it on every field. See GraphQL: the read-only subset.

A proxy forwarding its own hostname, an environment whose site UUIDs differ from production's, and a client omitting ?siteId= all produce the same symptom: correct-looking responses about the wrong site. Sending it explicitly on every call removes the ambiguity. For the operator's side of the same mechanism, see Multi-site: the domain field and host-based resolution.