Set up your project

Tenant authentication works only as far as the project allows. This page takes you from a new project to one where you know exactly who can sign in and who can register.

Changing a setting needs a project admin token. Reading needs any practitioner. An admin token comes from practitioner sign-in; set it once in your shell:

export OVOK_TOKEN='<access token of a project admin>'

1. Find your tenant code

Your apps send the tenant code in tenantCode. Read the code of your current project:

curl --get 'https://api.sandbox.ovok.com/organizations/code' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

Response field	Example	Meaning
`code`	`big-health-company`	The tenant code.
`projectId`	`5b1f0c0e-…`	The project it belongs to.

A 400 means the token has no project, or the project has no tenant code yet.

2. Read the settings you have

curl --get 'https://api.sandbox.ovok.com/v1/project/settings' \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

An unset Boolean shows as false, but five of the six sign-in switches behave as on when unset. Do not leave a switch to its default. Set each one to the value you intend. The behaviour is spelled out in unset settings.

3. Choose what you want

I want to…	Set
Let patients create their own account	`PATIENT_REGISTRATION_ENABLED` `true` and a default patient AccessPolicy on the project
Make patient onboarding invitation-only	`PATIENT_REGISTRATION_ENABLED` `false`, and `PATIENT_INVITATION_ENABLED` as you need it. Invitations are a second way to create a patient, so turn off the one you do not want.
Let practitioners create their own account	`DEFAULT_PRACTITIONER_ACCESS_POLICY` first, then `PRACTITIONER_REGISTRATION_ENABLED` `true`
Add practitioners by invitation instead	`PRACTITIONER_INVITATION_ENABLED` and `PRACTITIONER_APP_URL`
Pause patient sign-in	`PATIENT_LOGIN_ENABLED` `false`
Pause practitioner sign-in	`PRACTITIONER_LOGIN_ENABLED` `false`
Invite clinicians who register with a work email	`CLINICIAN_INVITE_ON_BUSINESS_EMAIL` `true`, a default practitioner AccessPolicy, a practitioner app URL and a patient app URL; see business-email sign-up

4. Give new users an AccessPolicy

An AccessPolicy decides what a new user can do. Ovok assigns one when it creates an account for you.

For	Where the policy comes from
New patients	`defaultPatientAccessPolicy` on the project. There is no settings endpoint for it. If you cannot write it yourself, contact Ovok. Patient registration is refused until it exists.
New practitioners	The text setting `DEFAULT_PRACTITIONER_ACCESS_POLICY`, which must be `AccessPolicy/<id>` of a policy in this project.

Set the practitioner policy:

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/project/settings/values/DEFAULT_PRACTITIONER_ACCESS_POLICY' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"value":"AccessPolicy/practitioner-policy-id"}'

Choose the least privilege you are happy to give a stranger: with self-registration on, anyone who can reach the route gets this policy. A policy from another project, or one that does not exist, answers 422 INVALID_SETTING_VALUE.

5. Switch the flows on or off

curl --request PUT \
  --url 'https://api.sandbox.ovok.com/v1/project/settings/PATIENT_REGISTRATION_ENABLED' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"enabled":true}'

The response is the full settings record, and the change applies to the next request.

A write can answer 409 if the project changed while it was being written. Read the settings again and retry.

6. Check that it works

Sign-in routes need no token, so you can test from a terminal. Send a request with an email that does not exist:

curl --request POST \
  --url 'https://api.sandbox.ovok.com/auth/tenant/Patient/login/start' \
  --header 'Content-Type: application/json' \
  --data '{"email":"nobody@example.com","password":"x","tenantCode":"big-health-company","codeChallenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"}'

You see	It means
`400` `Username or password is incorrect.`	The tenant code is right and patient sign-in is on. The email was just not an account.
`404` `Tenant not found.`	The tenant code is wrong.
`403` `Login is not enabled.`	`PATIENT_LOGIN_ENABLED` is `false`.

7. Map the emails your flows send

Some flows send an email, and an email is sent only when its template is mapped to one of yours.

Flow	Template	If it is not mapped
Patient registration	`PATIENT_WELCOME`	The new patient gets no welcome email.
Business-email sign-up	`CLINICIAN_SIGNUP_INVITE`	The person is registered as a patient.
Invitations	`INVITE_TO_PROJECT`, `PATIENT_INVITE` and others	If that route needs to send an email, its invitation behavior applies: the write is undone, the route falls back, or it reports an error. An existing account may be added without an email.

Set them up with Email templates. Practitioner registration sends no email.

Settings are checked at different moments

Not every route checks its setting at the same step. In particular, the practitioner sign-in checks PRACTITIONER_LOGIN_ENABLED at login/token, not at login/start, and the patient sign-in checks PATIENT_LOGIN_ENABLED at login/start, not at login/token. Each flow page lists where its check happens.

Turning a switch off stops new sign-ins. It does not end sessions that already exist; an access token stays valid for up to an hour.

1. Find your tenant code​

2. Read the settings you have​

3. Choose what you want​

4. Give new users an AccessPolicy​

5. Switch the flows on or off​

6. Check that it works​

7. Map the emails your flows send​

Settings are checked at different moments​

Related​