# Site scoping and the ?siteId= contract

URL: https://kywi-docs-production.up.railway.app/integrating/site-scoping-and-the-siteid-contract
Type: docPage

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.

## 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`.

`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.

## An unrecognized site id is not an error

A `?siteId=` naming no configured site and no known UUID — a typo, a stale id, a UUID from another environment — does not 400 or 404. It is discarded, and resolution falls through to the Host match and then to `sites[0]`. You get a 200 full of another site's content. On a single-site install that is invisible; on a multi-site one it is the failure mode to check first when a caller reads or writes the wrong site. This precedence — the same three steps on every site-scoped route — is 0.22.0 behaviour; before it, a request with no `?siteId=` could fall straight to `sites[0]` regardless of Host on routes that had not been migrated yet.

## 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](/governing/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](/integrating/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](/operating/multi-site-the-domain-field-and-host-based-resolution/).
