PRACTITIONER_INVITATION_ENABLED
Allow or stop practitioner invitations, which routes it covers, and which access policy an invited practitioner gets.
Controls whether project admins can invite practitioners by email. Practitioners are invited to join your project; they set a password from the emailed link.
| Type | Boolean setting |
| Change with | PUT /v1/project/settings/PRACTITIONER_INVITATION_ENABLED |
| Who can change it | Project admin |
| When unset | Practitioner invitations are on, although GET /v1/project/settings reports false |
| Set on new projects | true for child projects created with POST /v1/slim/project/child; not set by any other project-creation route |
| Needs | A practitioner app URL; for some routes a default practitioner AccessPolicy |
| Inherited | The switch is not. The app URL can fall back to the parent project. |
Turn practitioner invitations off
curl --request PUT \
--url 'https://api.sandbox.ovok.com/v1/project/settings/PRACTITIONER_INVITATION_ENABLED' \
--header "Authorization: Bearer ${OVOK_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{"enabled":false}'Routes it covers
Three routes add a practitioner to a project, and a fourth lets a patient share their record with one. They behave differently, so choose deliberately; the Invitations section explains when to use each.
| Route | Caller | Access policy of the invited practitioner | Link base |
|---|---|---|---|
| The Console's Members page | Project admin | None. The invited person is a project admin, with full access. | The Console that sent the invite |
POST /auth/invite with type Practitioner | Project admin | None. The default practitioner AccessPolicy is not applied, so no policy limits the member. | PRACTITIONER_APP_URL chain |
POST /v1/slim/invite/practitioner | A practitioner with permission to create practitioners | The accessPolicyId in the body | The request's Origin, else the deployment default. PRACTITIONER_APP_URL is not read. |
POST /v1/invites/record-share with recipient practitioner, and /accept (formerly /v1/invites/practitioner) | A patient makes the offer; a practitioner accepts | The default practitioner AccessPolicy for a new account, plus the patient's record as a share. This is not a colleague invitation. | PRACTITIONER_APP_URL chain; the request Origin is never used |
What callers see when it is off
| Route | Status | Message |
|---|---|---|
POST /auth/invite | 403 | Invitation is not enabled for this project. |
POST /v1/slim/invite/practitioner | 403 | Invitation is not enabled for this project. |
| The Console's Members page | 403 | Practitioner invitations are disabled for this project. |
POST /v1/invites/record-share with recipient practitioner | 403 | Invitation is not enabled for this project. |
Other responses you will meet
| Condition | Status | Response |
|---|---|---|
POST /auth/invite from a non-admin | 400 | Only admins can invite practitioners! |
POST /auth/invite with a projectId other than the token's | 400 | As a member of your project, you cannot invite members to other projects! |
| The Console's Members page, for an existing member | 409 | A member with this email already exists on this project. |
| No practitioner app URL resolves | 409 | code app_url_not_configured. Nothing is created. |
Gotchas
-
POST /auth/invitecreates a practitioner with no AccessPolicy. It does not readDEFAULT_PRACTITIONER_ACCESS_POLICY. -
POST /v1/slim/invite/practitionerignoresPRACTITIONER_APP_URL. The link points at whatever app made the request. A call made from a server, with noOrigin, falls back to the deployment default rather than your configured app. -
Someone who can already sign in gets access, not an email. An admin invite in the Console adds an existing account at once and sends no invitation; the Console says so.
-
GETshowsfalsefor a project that has never set it, but invitations work. Set the key to the value you intend. -
The refusal wording differs by route. Match on the status code, not the text.
-
Error identifiers are not in one field.
app_url_not_configuredis incode;invitation_not_configuredis inerror. -
Every invitation sends an email from a template you map.
INVITE_TO_PROJECTfor a project admin, andPRACTITIONER_INVITED_BY_PATIENTandPRACTITIONER_PATIENT_SHAREDfor a patient's share. Without a mapping, or with a provider that is notready, the invitation is undone. See Email templates.
Related
- Email templates, for the messages an invitation sends
- Invitations, the routes this switch gates
- PRACTITIONER_APP_URL
- DEFAULT_PRACTITIONER_ACCESS_POLICY
- PATIENT_INVITATION_ENABLED
Last updated on