Carers

A carer is someone a patient trusts with some of their readings, such as a family member. In FHIR a carer is a RelatedPerson linked to the patient. A carer signs in to the same tenant as the patient, usually in the patient app, and reads only what patients have shared with them.

What the project needsCopy Anchor Link

The carer switches are separate from the patient ones: PATIENT_LOGIN_ENABLED does not affect carers, and turning carer sign-in off does not affect patients. Projects created with POST /v1/slim/project/child start with both carer switches set to false.

Get an accountCopy Anchor Link

A carer account is created only when a carer accepts a patient's invite. There is no register route, because a FHIR RelatedPerson must point at a patient.

1. A patient shares readings with the carer's address: Share readings with a carer.
2. The carer opens the link in the email, chooses a password in your app, and your app posts it with the link's values, without a token.
3. The carer signs in with the address and that password.

Later invites from other patients of the same project are added to the same account. A carer of two projects has two accounts, one per tenant.

Sign inCopy Anchor Link

Carer sign-in is the same three-step PKCE flow as patient sign-in, under /auth/tenant/RelatedPerson. None of the steps needs a bearer token.

Create a code verifier and challenge for every attempt, as in step 0 of patient sign-in:

VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

Step 1: StartCopy Anchor Link

curl --request POST \
  --url 'https://api.sandbox.ovok.com/auth/tenant/RelatedPerson/login/start' \
  --header 'Content-Type: application/json' \
  --data "{
    \"email\": \"sam@example.com\",
    \"password\": \"${PASSWORD}\",
    \"tenantCode\": \"big-health-company\",
    \"codeChallenge\": \"${CHALLENGE}\"
  }"

The answer is 201 with nextStep: token with a sessionCode, or mfa with a loginId.

A patient or practitioner with the same email cannot sign in here, and a carer cannot sign in on the patient route.

Step 2: Verify the one-time code (only with MFA)Copy Anchor Link

curl --request POST \
  --url 'https://api.sandbox.ovok.com/auth/tenant/RelatedPerson/login/mfa' \
  --header 'Content-Type: application/json' \
  --data '{"loginId":"8c1e5a52-6f0b-4d9e-9a41-0b2f7c3d9e10","mfaToken":"123456"}'

The answer is 201 with { "nextStep": "token", "sessionCode": "…" }.

Step 3: Exchange the session code for tokensCopy Anchor Link

curl --request POST \
  --url 'https://api.sandbox.ovok.com/auth/tenant/RelatedPerson/login/token' \
  --header 'Content-Type: application/json' \
  --data "{\"sessionCode\":\"${SESSION}\",\"codeVerifier\":\"${VERIFIER}\"}"

The answer is 201 with accessToken, refreshToken, expiresIn (seconds), and the project and profile references. profile.reference is RelatedPerson/<id>.

If the carer had scheduled their account for deletion, signing in cancels it. Every error from these three steps takes at least a second.

Reset a passwordCopy Anchor Link

A carer resets a password the way a patient does: the account-level reset route with type RelatedPerson and your patient app's clientId.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v2/auth/reset-password' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "sam@example.com",
    "type": "RelatedPerson",
    "clientId": "7e3a9d52-1c6b-4f08-a5d4-b2e8c0f19a37"
  }'

• The answer is always the same 201 OperationOutcome, so it does not reveal whether the address has a carer account.
• The carer receives PATIENT_RESET_PASSWORD, with a link on the patient app URL: <patient app URL>/setpassword/<id>/<secret>.
• Your app finishes it with POST /v2/auth/reset-password/process. The old password stops working.
• Without clientId the answer is 422. See Send a password reset email.

What a carer can and cannot doCopy Anchor Link

A carer's token reads only what patients shared. Use the FHIR API with it.

Anything else is refused:

A carer keeps access until the patient ends the share with DELETE /v1/patient-sharing/shares/:consentId. The change applies on the carer's next request.

Sessions and the login switchCopy Anchor Link

• Turning RELATED_PERSON_LOGIN_ENABLED off refuses new sign-ins and the next token refresh with 403. A token already issued works until it expires, up to an hour.
• A session code from step 1 issued before the switch changed can still be exchanged at step 3.

GotchasCopy Anchor Link

• No invite, no account. Your app has no carer sign-up screen to build. Point carers to the invite email.
• Carers use the patient app. Invite and reset links are built on PATIENT_APP_URL. Your patient app needs a carer mode: different sign-in route, and screens that read shared data rather than the user's own.
• The patient record is redacted. Do not expect birthDate, gender or contact details on a shared Patient.
• A carer cannot list their shares yet. Search Patient to find who shares with them, and Observations by the codes you expect.
• Child projects start with carers off. Projects created with POST /v1/slim/project/child set both carer switches to false.

RelatedCopy Anchor Link

• Share readings with a carer
• Patient sign-in, the same flow for patients
• RELATED_PERSON_LOGIN_ENABLED
• RELATED_PERSON_INVITATION_ENABLED