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

InputWhere it comes from
Registry rowsList 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 originOne canonical https origin where artifact frames and descriptors are served. It is a deployment fact your installation operator gives you; no API returns it.
ViewerThe person's access tiers, or none without a session. See Viewer tiers.
API base URLYour own <origin>/api. See Forwarding.
SourcesThe 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 reporterYours.

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:

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-Id and X-Correlation-Id through, 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 →