# PATIENT_APP_URL

Canonical page: https://docs.ovok.com/settings-and-features/settings/patient-app-url

The root address of your patient app. Ovok builds the links in patient emails on it: set a password, accept an invitation, reset a password.

| | |
| --- | --- |
| Type | Text setting |
| Change with | `PUT /v1/project/settings/values/PATIENT_APP_URL` |
| Value | An `https` URL, or an app deep link such as `myapp://`. `null` removes it. |
| Who can change it | Project admin |
| When unset | Falls back to the parent project, older settings and the platform default, in that order. If nothing resolves, patient invitations answer `409`. |
| Set on new projects | Not set by any project-creation route |
| Inherited | Yes, from the **direct** parent project, at send time. `GET` does not show the inherited value. |

## Set it [#set-it]

```bash
curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/project/settings/values/PATIENT_APP_URL' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"value":"https://app.example.com"}'
```

The response is the full settings record, with the stored value under `values.PATIENT_APP_URL`.

## What the link looks like [#what-the-link-looks-like]

| Flow | Link |
| --- | --- |
| Patient invitation, password reset | `<app URL>/setpassword/<id>/<secret>` |
| Invitation for someone who already has an account | `<app URL>/accept-invite?invite=<id>&code=<code>` |
| "Continue as a patient" after a business-email sign-up | `<signup page>?continueAsPatientToken=<token>` |

| You set | The link is |
| --- | --- |
| `https://app.example.com/` | `https://app.example.com/setpassword/<id>/<secret>` |
| `https://app.example.com/patients` | `https://app.example.com/patients/setpassword/<id>/<secret>` |
| `myapp://` | `myapp:///setpassword/<id>/<secret>` |

A set-password link from an invitation works for 7 days after it is sent; password-reset links do not expire. See [the shared invitation-link rule](/invitations#limits-and-shared-behaviour).

Ovok stores the canonical form: no trailing slash and a lowercase host. `https://App.Example.com/patients/` is stored as `https://app.example.com/patients`.

## How the address is chosen [#how-the-address-is-chosen]

For a patient link, Ovok takes the first of these that exists:

1. `PATIENT_APP_URL` on the project.
2. `PATIENT_APP_URL` on the parent project.
3. The older `PATIENT_SIGNUP_URL` on the project, then on the parent. Only its origin is used (`https://app.example.com/register` gives `https://app.example.com`).
4. The `Origin` of the request, only for flows that allow it and only if that origin is on the platform's allowed-origins list.
5. The platform default, if your environment has one.

The "continue as a patient" link is the exception: it uses `PATIENT_SIGNUP_URL` in full, ahead of `PATIENT_APP_URL`, whenever that older setting is present.

Patient invitations never use the request `Origin`, because the caller is not the patient and the header can be forged. If nothing else resolves, the invitation is refused with `409` and `code` [`app_url_not_configured`](/errors/app-url-not-configured), and **nothing is created**.

## What is accepted [#what-is-accepted]

| Rule | Detail |
| --- | --- |
| Scheme | `https`, on any host, or an app deep link `scheme://[host][/path]`. `http` is accepted only for `localhost` and `127.0.0.1`, and only where the API allows that origin. |
| Not allowed | Userinfo (`user:pass@`), a query (`?`), a fragment (`#`), an opaque `scheme:path`, and web, script or local schemes used as a deep link, such as `javascript:`, `data:`, `file:` and `mailto:`. |
| Length | 2048 characters or fewer, after canonicalisation. |
| Not this API | A web URL on the host of the API itself is refused. A link there would open the API, not your app. |

| Response | Meaning |
| --- | --- |
| `422` with `code` [`INVALID_SETTING_VALUE`](/errors/invalid-setting-value) | The value is not a valid app URL or deep link. An empty string is invalid; send `null` to remove the setting. |
| `400` with `code` [`APP_URL_NOT_ALLOWED`](/errors/app-url-not-allowed) | The URL points at the API's own host. |
| `400` with `code` [`UNKNOWN_SETTING`](/errors/unknown-setting) | The key is not a text setting. The body lists `acceptedKeys`. |
| `403` | The caller is not a project admin. |
| `409` | The project changed during the write. Read the settings again and retry. |

## Gotchas [#gotchas]

- **`GET` shows only this project's stored value.** A child project that inherits its parent's URL shows `null`, even though links resolve. Do not use `null` to conclude that links will fail.
- **`GET` shows the stored text, not the checked form.** A value written outside the settings API that fails the checks above is skipped when an email is sent, with a warning in the logs, and the next address in the list is used. Re-save the value through the API to get it validated.
- **Business-email sign-up needs it.** The "continue as a patient" link in the clinician invitation is built from it (or from the older `PATIENT_SIGNUP_URL`, used whole). Without one, the invitation is undone and the person is registered as a patient. See [CLINICIAN_INVITE_ON_BUSINESS_EMAIL](/settings-and-features/settings/clinician-invite-on-business-email).
- **The inheritance is one level.** Only the direct parent is consulted.
- **Order matters across keys.** A new `PATIENT_APP_URL` on the parent wins over an older `PATIENT_SIGNUP_URL` on the child.
- **You edit only your own project.** There is no way to set a child's URL from the parent's session.
- **Password resets never fail on a missing URL.** If nothing resolves, the reset email can go out without a usable link. Set the URL before you rely on resets.
- **Video-call emails use a separate link.** They take their dashboard address from platform configuration, not from this setting.
- **Deep links lose a path in older settings.** Use `PATIENT_APP_URL` if the patient app lives under a path, because `PATIENT_SIGNUP_URL` contributes only its origin to set-password links.

- **The same address is the `baseUrl` of every patient email.** Your email templates receive it as the `baseUrl` parameter. See [the template parameters](/email-templates/template-catalogue#parameters).

## Related [#related]

- [Email templates](/email-templates), where these links appear
- [Invitations](/invitations)
- [PRACTITIONER_APP_URL](/settings-and-features/settings/practitioner-app-url)
- [PATIENT_INVITATION_ENABLED](/settings-and-features/settings/patient-invitation-enabled)
- [PATIENT_SHARING_ENABLED](/settings-and-features/settings/patient-sharing-enabled)
