Video-call join access

Use these endpoints to issue a LiveKit room URL and JWT for one participant. The JWT is a bearer credential: deliver it only to the participant who should join the appointment.

Operation	Method	Path	Caller
Guest access	POST	/video-call/livekit/guest-access/:appointmentId	Signed-in Practitioner
Signed-in user access	POST	/video-call/livekit/user-access/:appointmentId	Signed-in Practitioner or Patient
Read my access grant	GET	/video-call/livekit/access-permission/:appointmentId	Signed-in grant recipient

Each request needs a bearer token. A RelatedPerson cannot use signed-in user access. A Patient can get a join token only after a Practitioner has started the call and Ovok has created a grant naming that Patient as a recipient.

Create guest access

Ask Ovok for guest access when a participant has no Ovok account. The caller must have a Practitioner profile.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/video-call/livekit/guest-access/2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"guestEmail":"guest@example.org"}'

Body field	Required	Description
guestEmail	Yes	Valid email address. It is used as the guest's display name in the room.

Guest tokens are valid from one hour before the appointment's start until one hour after its end. Guest tokens do not have room-admin rights. This route returns credentials; it does not send email.

Create signed-in user access

Practitioners can request their own access. Patients must first be named in the appointment's active access grant. Starting a call creates or refreshes that grant; see start the call.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/video-call/livekit/user-access/2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

A Practitioner joins as a room admin. A Patient joins without room-admin rights. The display name is the Practitioner's profile name when available; for a Patient it is the account email, falling back to user-<profile-id>.

Signed-in user tokens are valid from one hour before the request until 24 hours after the request. This lifetime is based on request time, not the appointment's start and end.

Successful response

Both access-token routes return:

Response field	Meaning
videoCallUrl	Join URL for the configured LiveKit application. It includes the JWT and the appointment passphrase.
livekitJwt	Signed LiveKit access token for the appointment room.
passphrase	Appointment passphrase used by the join experience.

Each access request creates a new JWT. Previously issued tokens remain valid until their own expiration time.

Read the access grant

This returns the caller's CommunicationRequest for the appointment. It returns 403 when the caller is not one of the grant's recipients.

curl --request GET \
  --url 'https://api.sandbox.ovok.com/video-call/livekit/access-permission/2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

Response field	Meaning
resourceType	CommunicationRequest.
id	FHIR resource id for the access grant.
identifier	Ovok identifier marking this as a video-call access request.
basedOn[]	Appointment reference, Appointment/<appointment-id>.
status	Grant status. The active-call operation writes active.
sender	Practitioner or other permitted caller who started the call; display is present when the profile has a name.
recipient[]	Practitioner and Patient profile references granted access to this appointment.

The response omits FHIR meta.

Errors to account for

Status	Common cause
400	Invalid appointment id, missing user/profile, invalid guest email, or appointment cannot be read.
401	Missing or invalid bearer token. A Patient without an access grant is also refused by the user-access route.
403	Guest-access caller is not a Practitioner, or the caller is not a recipient of the requested access grant.

Continue with notifications and email to grant Patient access and communicate with participants.