Embed the auth-check UI

The auth-check UI shows Hermes’ analysis of an authorization document as an iframe in your own product. Use it for any screen that shows auth-check results to your users.

The iframe updates whenever the analysis improves, so you never track changes to the analysis schema yourself, and your API key never reaches the user’s browser.

1. Get an embed token

An embed token is valid for one document for one hour. Most integrations already have one, because it comes back on calls you make anyway.

From a patient or record request. GET .../patients/{patientId} and GET .../record-requests/{recordRequestId} include an embedToken whenever an authorization document is on file, and null until one is uploaded. Use this when you already fetch the patient or request to render the page.

From a standalone upload. For a document uploaded outside any patient, send a StandaloneAuthCheckBody with PUT /v0/auth-check/{filename}: the patient’s firstName, lastName and dateOfBirth, plus an optional referenceId. The response carries both the uploadUrl and the embedToken, so the iframe is ready as soon as the upload finishes.

referenceId is your own identifier for the patient, such as an MRN, of up to 255 characters. It is not part of the token: it is stored with the submission and shown in the auth-checker’s Submissions tab, so you can match each submission back to your patient.

From an explicit request. POST /v0/auth-check/{filename}/embed-token with the same body returns a fresh token. Use it when you uploaded before you had the patient’s details, or to replace an expired token on a page that stays open.

All three calls need your API key. The token itself is safe to hand to the user’s browser: it cannot be altered, and a tampered or expired one returns 401.

2. Add the iframe

Point an iframe at /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 iframe needs only the token, not a session, so it works inside any site.

While the analysis is still running, the iframe shows the document beside a progress indicator and reloads itself until the result is ready. You don’t need to poll.

3. Show a badge in tables and lists

Where the full checklist doesn’t fit, such as a row in a table, use /ui/auth-check/embed/badge?token=<token>. It shows a compact passed, warning or failed summary, the same one Hermes uses 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>

One token works for both. Render the badge on each row, and open the full iframe with the same token when the user clicks through.

Refresh an expired token

Tokens expire one hour after they are created. Patient and record-request responses include a fresh one every time, so re-fetching on page load is usually enough. For a page that stays open longer, call POST /v0/auth-check/{filename}/embed-token again.

Read the analysis as JSON

To work with the verdicts in your own code instead, see Check an authorization with the API.

Next steps

• Embed the site finder: let users find a facility inside your product.
• Embed clinical data: show a patient’s visits and results.