Skip to main content

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.

TypeText setting
Change withPUT /v1/project/settings/values/PATIENT_APP_URL
ValueAn https URL, or an app deep link such as myapp://. null removes it.
Who can change itProject admin
When unsetFalls back to the parent project, older settings and the platform default, in that order. If nothing resolves, patient invitations answer 409.
Set on new projectsNot set by any project-creation route
InheritedYes, from the direct parent project, at send time. GET does not show the inherited value.

Set it​

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.

FlowLink
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 setThe link is
https://app.example.com/https://app.example.com/setpassword/<id>/<secret>
https://app.example.com/patientshttps://app.example.com/patients/setpassword/<id>/<secret>
myapp://myapp:///setpassword/<id>/<secret>

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​

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, and nothing is created.

What is accepted​

RuleDetail
Schemehttps, 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 allowedUserinfo (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:.
Length2048 characters or fewer, after canonicalisation.
Not this APIA web URL on the host of the API itself is refused. A link there would open the API, not your app.
ResponseMeaning
422 with code INVALID_SETTING_VALUEThe 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_ALLOWEDThe URL points at the API's own host.
400 with code UNKNOWN_SETTINGThe key is not a text setting. The body lists acceptedKeys.
403The caller is not a project admin.
409The project changed during the write. Read the settings again and retry.

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.
  • 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.