# Video-call join access

Canonical page: https://docs.ovok.com/video-calls/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` | `/v1/video-call/livekit/guest-access/:appointmentId` | Signed-in Practitioner |
| Signed-in user access | `POST` | `/v1/video-call/livekit/user-access/:appointmentId` | Signed-in Practitioner or Patient |
| Read my access grant | `GET` | `/v1/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 [#create-guest-access]

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

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/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 [#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](/video-calls/notifications-and-email#start-the-call-and-notify-participants).

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/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 [#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 [#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.

```bash
curl --request GET \
  --url 'https://api.sandbox.ovok.com/v1/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 [#errors-to-account-for]

| Status | Common cause |
| --- | --- |
| `400` | The session has no user or profile, or the appointment cannot be found or read. |
| `422` | The `appointmentId` is not a UUID, or the body fails validation, for example an invalid guest email. `errors` names each invalid field. |
| `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](/video-calls/notifications-and-email) to grant Patient access and communicate with participants.
