Embedding the auth-check UI

Hermes Health renders the auth-check analysis as a server-rendered UI that you can drop into your own product as an iframe. This is the recommended integration path for any surface that displays auth-check results to end users.

Why embed?

The raw auth-check analysis schema (Analysis, AuthCheck, CheckItem, AdditionalDocuments, and friends) changes frequently — we ship updates as we expand coverage for new document types, new legal requirements, and new edge cases surfaced by production usage. Consumers that embed the iframe pick up every improvement automatically and never need to handle schema drift. Consumers that marshal the raw schema themselves accept ongoing maintenance cost.

Embedding also means you never have to forward your backend API key to an end-user browser — the embed token is scoped to a single PDF and expires in an hour.

1. Get an embed token

You almost never need a dedicated call for this — the token rides along on a response you already make. Each path below requires an authenticated backend call with your bearer token.

a. Eager field on patient / record-request responses. Every GET .../patients/<id> and GET .../record-requests/<id> response includes a ready-to-use embedToken field when the authorization PDF is present. No extra round-trip is needed — this is the preferred path when you already fetch the patient or record request on page load.

b. Returned by the standalone upload request. For the standalone auth-checker, where the document is uploaded outside any patient context, send the StandaloneAuthCheckBody body when you request the upload URL: PUT /v0/auth-check/{filename} then returns the token on the embedToken field of its FileResponse, alongside the uploadUrl. This is the preferred standalone path — a single call yields both the upload URL and the token, so the iframe is ready as soon as the upload finishes. That body is the patient’s firstName, lastName and dateOfBirth, plus an optional referenceId: your own identifier for the patient, such as an MRN, at most 255 characters. The reference is not part of the token; it is stored with the submission and shown in the auth-checker’s Submissions tab, so each submission can be matched back to your patient.

c. Explicit mint — for late binding and rotation. POST /v0/auth-check/{filename}/embed-token accepts the same StandaloneAuthCheckBody body, including the optional referenceId, and returns an EmbedTokenResponse { token }. Reach for this only when (b) doesn’t fit: you uploaded before you had the patient context (so you omitted the body and got embedToken: null), or you need to rotate an expired token for a long-lived embed.

Whichever path you use, the resulting token is a stateless string sealed with authenticated encryption (AES-256-CTR encrypt-then-MAC with HMAC-SHA256, keyed apart from the generic URL-query oracle and verified in constant time before any field is trusted). It carries the patient info, the PDF’s S3 key, the minting company, and an expiry (one hour from mint). No database lookup happens at render time, and a forged or tampered token is rejected with 401.

Beyond the iframe, the standalone JSON endpoint requires the same token: GET /v0/auth-check/{filename}?token=<token> uses its patient info to run the patient-comparison verdicts (patientName, patientDateOfBirth, signerName, and friends). A null verdict always means the check did not run, not that it passed.

2. Drop the iframe into your page

Point an iframe at GET /ui/auth-check/embed?token=<token>:

<iframe
  src="https://api.hermeshealth.ai/ui/auth-check/embed?token=YOUR_TOKEN"
  width="100%"
  height="800"
  style="border: 0;"
  title="Auth-check analysis"></iframe>

The embed route is token-authed only — no session cookie is required — so it is safe to render inside a third-party site. The token may be passed to the end user.

Compact badge variant

For dense surfaces — table rows, list views, dashboards — where the full checklist doesn’t fit, point an iframe at GET /ui/auth-check/embed/badge?token=<token> instead. It renders only a compact passed / warning / failed stoplight summary (the same per-row badge Hermes shows in its own patient table):

<iframe
  src="https://api.hermeshealth.ai/ui/auth-check/embed/badge?token=YOUR_TOKEN"
  width="130"
  height="28"
  style="border: 0;"
  title="Auth-check summary"></iframe>

The two endpoints share the same API: identical token auth, identical framing policy — only the path differs, and one token works on both. If you are integrating the full auth-check iframe, use this badge alongside it rather than building your own summary from the raw analysis schema: render the badge per row, and open the full embed with the same token when the user clicks through.

Pending-state behavior

If the analysis is still processing when the iframe loads, the full embed renders a side-by-side view showing the PDF and a pending spinner (the badge embed shows a compact placeholder pill), and both automatically reload themselves (first poll after 45 seconds, then every 5 seconds) until analysis is ready. Consumers do not need to implement any polling loop of their own.

Token lifetime

Embed tokens expire one hour after they were minted. PatientOutput and RecordRequestOutput mint fresh tokens on every fetch, so for session-style usage it’s typically enough to read the token straight off the response and re-fetch on page navigation. For long-lived embeds, call POST /v0/auth-check/{filename}/embed-token again to rotate.