Step 3 · Add the patients function
A Supabase Edge Function that checks the nurse's Ovok token, serves the register and creates each patient's pseudonymous Ovok Patient.
The patients Edge Function is the only way into the register. It trusts Ovok for who the nurse is, so the kiosk needs one sign-in, and it creates the Ovok Patient with the nurse's own token, so Supabase holds no Ovok secret.
Before you begin
- Supabase running from step 1.
- The four values from step 2.
Configure the functionServer-side
Copy supabase/functions/.env.example to supabase/functions/.env and fill it in. supabase start loads this file for local functions.
OVOK_BASE_URL=https://api.sandbox.ovok.com
OVOK_PROJECT_ID={{PROJECT_ID}}
PATIENT_IDENTIFIER_SYSTEM=https://kiosk.example.org/patient-idThe kiosk sends an Ovok token, not a Supabase one, so supabase/config.toml turns off Supabase's own token check for this function:
[functions.patients]
verify_jwt = falseCheck who is callingServer-side
Every request carries the nurse's Ovok access token. The function asks Ovok who it belongs to with GET /v1/auth/me, and lets in only practitioners of your project.
const response = await fetchImpl(url("v1/auth/me"), {
headers: { authorization: `Bearer ${token}`, accept: "application/json" },
});
if (REFUSED_TOKEN_STATUSES.has(response.status)) return null;
if (!response.ok) throw new OvokUnavailableError(response.status);
const me = (await response.json()) as AuthMe;- A missing token answers
401withWWW-Authenticate: Bearer. A token Ovok refuses answers401too. - A patient, or a practitioner of another project, answers
403. - Ovok being unreachable answers
502, so the kiosk tells the nurse to try again.
Create the pseudonymous PatientServer-side
When a patient is registered, the function creates their Ovok Patient. The body holds the pseudonym and nothing else, and If-None-Exist makes the create conditional: a retry finds the Patient it made before.
const response = await fetchImpl(url("fhir/R4/Patient"), {
method: "POST",
headers: {
authorization: `Bearer ${token}`,
"content-type": "application/fhir+json",
"if-none-exist": new URLSearchParams({ identifier: `${identifierSystem}|${pseudonym}` }).toString(),
},
body: JSON.stringify({
resourceType: "Patient",
active: true,
identifier: [{ system: identifierSystem, value: pseudonym }],
}),
});The function stores the returned id as ovok_patient_id. Every answer passes through one helper that creates the Patient first when a row has none, so a register row never leaves the function without its Ovok Patient.
The routesServer-side
| Method and path | Body | Answers |
|---|---|---|
POST /functions/v1/patients/_search | { "cardCode": "WARD-0042" } | 200 with the patient, 404 for an unknown card, 422 for a malformed code |
POST /functions/v1/patients | cardCode, givenName, familyName, birthDate | 201 with Location, 409 when the card is taken, 422 for invalid fields |
GET /functions/v1/patients/{id} | 200 with the patient, 404 |
The card code travels in a POST body, not the URL, so it never lands in an access log.
Verify your integration
Register a test patient with a nurse's token:
curl -i "http://127.0.0.1:54321/functions/v1/patients" \
-H "Authorization: Bearer {{ACCESS_TOKEN}}" \
-H "Content-Type: application/json" \
-d '{"cardCode":"WARD-0042","givenName":"Mara","familyName":"Test","birthDate":"1951-04-09"}'You get 201 Created, a Location header and the patient with its ovokPatientId. Read that Patient from Ovok: it has resourceType, id, meta, active and identifier, and no name or birth date.
Troubleshooting
401with a fresh token: checkOVOK_BASE_URL. The function must reach the same Ovok environment the nurse signed in to.403for a nurse: checkOVOK_PROJECT_IDagainstproject.idfromGET /v1/auth/me.502: the nurse's access policy may not allow Patient create. The function's log lineovok request failedcarries Ovok's status.
Next step
Continue to step 4: build the kiosk app.
Last updated on