Embedding

Embedding the member view

The embedded member view is Protearc's member page inside your own app: read only, in your organization's brand colour and logo, with the line "Results by Protearc". Your server asks the API for a token; your page puts the token in an iframe address.

Issue a token

POST /v1/embeds takes the member's id (PA-..., as returned by an order) and the id of a clinician in your organization, the person the view is opened for. The response is a token starting emb_ and the time it stops working.

A token is good for one organization, one clinician and one member, for 10 minutes from the moment it is issued. It cannot be extended: issue a new one. If the member or the clinician is not in your organization, or does not exist, the answer is 404 and no token is issued. A clinician id is listed for a signed-in administrator by GET /v1/settings/team.

curl -X POST http://localhost:8000/v1/embeds \
  -H "Authorization: Bearer ptk_sandbox_meridian_demo" \
  -H "Content-Type: application/json" \
  -d '{"member_id": "PA-0001", "clinician_id": "<clinician id>"}'

import requests

r = requests.post(
    "http://localhost:8000/v1/embeds",
    headers={"Authorization": "Bearer ptk_sandbox_meridian_demo"},
    json={"member_id": "PA-0001", "clinician_id": "<clinician id>"},
)
embed = r.json()
print(embed["token"], embed["expires_at"])

const r = await fetch("http://localhost:8000/v1/embeds", {
  method: "POST",
  headers: {
    Authorization: "Bearer ptk_sandbox_meridian_demo",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ member_id: "PA-0001", clinician_id: "<clinician id>" }),
});
const embed = await r.json();
console.log(embed.token, embed.expires_at);

json Response 201 (synthetic example)

{
  "token": "emb_example.not.a.real.token",
  "expires_at": "2026-11-04T16:40:00Z"
}

Show it in an iframe

Build the address from the API host, the path /embed, and a URL fragment holding the member and the token. The fragment (after #) is never sent to a server, so the token stays out of logs. Issue the token on your server, at the moment the page is opened, and pass the address to the page.

After the 10 minutes the view shows "Session ended, reopen from your app." Issue a new token and load a new address.
The view reads its data from GET /v1/embed/members/{member_ref} with the token as a bearer token. The token works for that member only; any other member is answered 404, and a missing or invalid token 401.
A browser lets a page frame /embed only if the page's origin is in the server's frame-ancestors list. The local demo allows its own origin and http://localhost:8001; a page on any other origin is refused by the browser until its origin is added.

html Your page

<iframe
  src="http://localhost:8000/embed#member=PA-0001&token=emb_..."
  title="Protearc results"
  width="100%"
  height="720"
  style="border:0"
></iframe>