Settings

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.

TypeBoolean setting
Change withPUT /v1/project/settings/PRACTITIONER_INVITATION_ENABLED
Who can change itProject admin
When unsetPractitioner invitations are on, although GET /v1/project/settings reports false
Set on new projectstrue for child projects created with POST /v1/slim/project/child; not set by any other project-creation route
NeedsA practitioner app URL; for some routes a default practitioner AccessPolicy
InheritedThe 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.

RouteCallerAccess policy of the invited practitionerLink base
The Console's Members pageProject adminNone. The invited person is a project admin, with full access.The Console that sent the invite
POST /auth/invite with type PractitionerProject adminNone. The default practitioner AccessPolicy is not applied, so no policy limits the member.PRACTITIONER_APP_URL chain
POST /v1/slim/invite/practitionerA practitioner with permission to create practitionersThe accessPolicyId in the bodyThe 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 acceptsThe 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

RouteStatusMessage
POST /auth/invite403Invitation is not enabled for this project.
POST /v1/slim/invite/practitioner403Invitation is not enabled for this project.
The Console's Members page403Practitioner invitations are disabled for this project.
POST /v1/invites/record-share with recipient practitioner403Invitation is not enabled for this project.

Other responses you will meet

ConditionStatusResponse
POST /auth/invite from a non-admin400Only admins can invite practitioners!
POST /auth/invite with a projectId other than the token's400As a member of your project, you cannot invite members to other projects!
The Console's Members page, for an existing member409A member with this email already exists on this project.
No practitioner app URL resolves409code app_url_not_configured. Nothing is created.

Gotchas

  • POST /auth/invite creates a practitioner with no AccessPolicy. It does not read DEFAULT_PRACTITIONER_ACCESS_POLICY.

  • POST /v1/slim/invite/practitioner ignores PRACTITIONER_APP_URL. The link points at whatever app made the request. A call made from a server, with no Origin, 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.

  • GET shows false for 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_configured is in code; invitation_not_configured is in error.

  • Every invitation sends an email from a template you map. INVITE_TO_PROJECT for a project admin, and PRACTITIONER_INVITED_BY_PATIENT and PRACTITIONER_PATIENT_SHARED for a patient's share. Without a mapping, or with a provider that is not ready, the invitation is undone. See Email templates.

Last updated on

On this page