Embedding the site finder

The site finder is also available as an embeddable, server-rendered UI. Unlike the read-only auth-check embed, this surface is interactive: the embedded user can submit facility details, run the finder, review the closest matches (an expandable in-page list — no popups), create a new site from the enriched proposal when nothing matches, and trigger AI research on a site.

1. Mint an embed token

POST /v0/site-finder/embed-token (authenticated with your bearer token) accepts a { "parentOrigin": "https://your-approved-host.example" } body and returns an EmbedTokenResponse { token }. parentOrigin is the exact origin of the page that frames the iframe: https://host[:port] with no path, query, fragment, credentials or wildcard, on the deployment’s approved browser-origin allowlist. Anything else is answered with 400. The iframe response binds frame-ancestors to that exact origin. The token is a stateless, authenticated-encrypted string scoped to your company and the minting user.

Deprecated: omitting the body or parentOrigin still mints a token, framed by any page (legacy wildcard framing). A later release will require parentOrigin and answer a mint without it with 400, so send it now.

Everything the embedded user does — searches, site creation, research — is attributed, billed, and rate-limited as the minting user, so mint with a service account if you want a clean audit trail.

2. Drop the iframe into your page

Point an iframe at GET /ui/site-finder/embed?token=<token>:

<iframe
  src="https://api.hermeshealth.ai/ui/site-finder/embed?token=YOUR_TOKEN"
  width="100%"
  height="900"
  style="border: 0;"
  title="Site finder"></iframe>

The embed routes are token-authed only — no session cookie is required — so the token may be passed to the end user, but the iframe can only be framed by the exact approved parentOrigin sealed into it. A token minted without one (deprecated) can be framed by any page. You can pre-fill the search form by appending query parameters to the iframe URL: name, addressLine1, addressLine2, city, state, zip, and isFacility.

Token lifetime

Site-finder embed tokens expire one hour after minting, and every action inside the embed re-validates the token — a search or create attempted after expiry fails with 401. Mint a fresh token each time you render the page hosting the iframe rather than caching tokens. Deleting the minting user (or removing their site-finder permission) invalidates outstanding tokens immediately.