Update a project text setting

Sets one text setting of your current project, such as an app URL or a default access policy, or removes it with null.

Auth: bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy. Scope: the caller's project (from the token).

Behaviour

• :key must be one of the text keys returned in values by GET /v1/project/settings. It may be URL-encoded.
• value is trimmed and checked for the key's kind:
  • App URL keys (PATIENT_APP_URL, PRACTITIONER_APP_URL, PATIENT_SIGNUP_URL, CLINICIAN_DASHBOARD_URL): see App URLs below. The canonical form is stored.
  • Access policy keys (DEFAULT_PATIENT_ACCESS_POLICY, DEFAULT_PRACTITIONER_ACCESS_POLICY, CLINICIAN_INVITE_ACCESS_POLICY): AccessPolicy/<id> of an AccessPolicy in this project.
• null removes the entry. Every other entry of Project.setting[] is kept as it is.
• DEFAULT_PATIENT_ACCESS_POLICY is written to Project.defaultPatientAccessPolicy, not to Project.setting[]. Removing it turns patient registration and patient invitations off: see effectiveSettings in GET /v1/project/settings.
• The write only succeeds if the project did not change since the server read it; otherwise it answers 409.
• The response is the full settings envelope after the write, as GET /v1/project/settings returns it.

App URLs

PATIENT_APP_URL and PRACTITIONER_APP_URL are the app roots that links in emails are built on: https://app.example.com gives https://app.example.com/setpassword/<id>/<secret>.

• Resolution order, per audience: the project's setting, then the parent project's, then the legacy setting (PATIENT_SIGNUP_URL or CLINICIAN_DASHBOARD_URL, on the project then its parent), then the request Origin for flows that allow it, then the deployment default.
• For set-password and invite links, only the origin of PATIENT_SIGNUP_URL is used: https://app.example.com/register gives https://app.example.com, and vitalwise://register gives vitalwise://. Set PATIENT_APP_URL if the patient app lives under a path.
• The continue-as-patient link (a business-address sign-up turned into a clinician invite) uses PATIENT_SIGNUP_URL in full whenever it is set, ahead of PATIENT_APP_URL.
• An app URL is an https URL on any host (http only on localhost), or an app deep link scheme://[host][/path]: vitalwise:// gives vitalwise:///setpassword/<id>/<secret>. A web URL on this API's own host is refused, and a stored one is skipped when an email is sent.
• Only the canonical form is stored and used, without a trailing slash. Userinfo, a query, a fragment, an opaque scheme:path, and web, script or local schemes used as a deep link (javascript:, data:, file: and others) are refused on write and skipped on send.
• An invite with no app URL for its audience answers 409 app_url_not_configured and creates nothing.
• An unknown :key returns 400 UNKNOWN_SETTING with the accepted keys. A web app URL on this API's own host returns 400 APP_URL_NOT_ALLOWED. A value that is not valid for the key returns 422 INVALID_SETTING_VALUE.

Example

curl -X PUT 'https://api.sandbox.ovok.com/v1/project/settings/values/PRACTITIONER_APP_URL' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{ "value": "https://app.example.com" }'