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.

supabase/functions/.env
OVOK_BASE_URL=https://api.sandbox.ovok.com
OVOK_PROJECT_ID={{PROJECT_ID}}
PATIENT_IDENTIFIER_SYSTEM=https://kiosk.example.org/patient-id

The kiosk sends an Ovok token, not a Supabase one, so supabase/config.toml turns off Supabase's own token check for this function:

supabase/config.toml
[functions.patients]
verify_jwt = false

Check 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.

supabase/functions/patients/ovok-gateway.ts
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 401 with WWW-Authenticate: Bearer. A token Ovok refuses answers 401 too.
  • 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.

supabase/functions/patients/ovok-gateway.ts
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 pathBodyAnswers
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/patientscardCode, givenName, familyName, birthDate201 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

  • 401 with a fresh token: check OVOK_BASE_URL. The function must reach the same Ovok environment the nurse signed in to.
  • 403 for a nurse: check OVOK_PROJECT_ID against project.id from GET /v1/auth/me.
  • 502: the nurse's access policy may not allow Patient create. The function's log line ovok request failed carries Ovok's status.

Next step

Continue to step 4: build the kiosk app.

Last updated on

On this page