Hosting Web Biomes in Your Own App
A web biome can be mounted by a frontend other than the Xema web app. This page is the contract your app and backend meet: what you supply, which Xema routes feed it, and what your backend must forward. The package-level steps and a runnable catch-all route are in the README of the Next.js web host package (web-host-next) and are not repeated here.
What you build
Your browser calls Xema through your own backend-for-frontend (BFF) that holds the person's session. Xema web biomes run in your page through a web host provider. The host verifies each web artifact, runs it isolated in a sandboxed frame, and lets it call only the operations its registration declares.
The provider's inputs
| Input | Where it comes from |
|---|---|
| Registry rows | List web biomes (WebBiomesController_list) with includeWebArtifacts=true, called as the person with the X-Xema-Org-Id header. Keep the rows whose loader kind is WEB_ARTIFACT. |
| Artifact origin | One canonical https origin where artifact frames and descriptors are served. It is a deployment fact your installation operator gives you; no API returns it. |
| Viewer | The person's access tiers, or none without a session. See Viewer tiers. |
| API base URL | Your own <origin>/api. See Forwarding. |
| Sources | The host-side services the biome sees: session, request context, theme, locale, toasts, page metadata and error reporting. Your app owns them. |
| Loading, forbidden and unavailable views, and an error reporter | Yours. |
Every call is made as the person, never as a workload, and is scoped to one organisation: the organisation comes from the X-Xema-Org-Id header, which the host stamps on each call so a biome cannot choose its own.
Viewer tiers
The viewer states whether the person is an organisation admin and which platform roles they hold (owner, admin, operator). A route declares the tier it needs, and the host refuses a viewer that does not satisfy it. Derive the viewer from two person-session calls:
- Get the current user (
UsersController_getMe) for the platform roles. - Get the current user's organizations (
UsersController_getMyOrganizations) for the person's role in the active organisation.
An organisation admin is the organisation owner or admin role only; a platform admin without the organisation role is not one. This decides what renders; the services enforce the same authority on every call.
Forwarding through your BFF
An isolated biome calls only the operations its registration declares, at <API base URL>/<service><path>. Your BFF must:
- forward everything under
/api/<service>/to the Xema API host for each service your biomes use, at least the biome host and identity services; - keep the method, body and the person's session unchanged;
- pass
X-Xema-Org-Id,X-Project-IdandX-Correlation-Idthrough, and add no tenant headers of its own.
Content Security Policy
Add the artifact origin to your page's frame-src directive. The host package builds the directive for you from the origin.
Mounting
Render the provider around a catch-all route in your app, and mount the biome route with scope org. The Next.js package ships both; the README has the complete route.
Previous: ← Manifest Reference
Next: Examples →