# Update a project text setting

Canonical page: https://docs.ovok.com/api/projects/update-a-project-text-setting

`PUT /v1/project/settings/values/{key}`

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

```bash
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" }'
```