# Step 3 · Add the patients function

Canonical page: https://docs.ovok.com/guides/staffed-kiosk/add-the-patients-function

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 [#before-you-begin]

- Supabase running from step 1.
- The four values from step 2.

## Configure the function [Server-side] [#configure-the-function-server-side]

Copy `supabase/functions/.env.example` to `supabase/functions/.env` and fill it in. `supabase start` loads this file for local functions.

~~~dotenv title="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:

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

## Check who is calling [Server-side] [#check-who-is-calling-server-side]

Every request carries the nurse's Ovok access token. The function asks Ovok who it belongs to with [`GET /v1/auth/me`](/authentication/account/get-account-information), and lets in only practitioners of your project.

~~~ts title="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 Patient [Server-side] [#create-the-pseudonymous-patient-server-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](/api/fhir/r4/patient): a retry finds the Patient it made before.

~~~ts title="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 routes [Server-side] [#the-routes-server-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 [#verify-your-integration]

Register a test patient with a nurse's token:

~~~bash
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 [#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 [#next-step]

Continue to [step 4: build the kiosk app](/guides/staffed-kiosk/build-the-kiosk-app).
