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.
| Name | Type | Default | Description |
|---|---|---|---|
?siteId= | config slug or DB UUID | checked 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 header | a configured domain or alias | checked 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.
/api/v1/content/page?siteId=docsNo authsiteId=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.