# Set up your project

Canonical page: https://docs.ovok.com/authentication/project-setup

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](/authentication/practitioner-login); set it once in your shell:

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

## 1. Find your tenant code [#1-find-your-tenant-code]

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

```bash
curl --get 'https://api.sandbox.ovok.com/v1/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 [#2-read-the-settings-you-have]

```bash
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](/settings-and-features#defaults-and-dependencies).

## 3. Choose what you want [#3-choose-what-you-want]

| I want to… | Set |
| --- | --- |
| Let patients create their own account | [`PATIENT_REGISTRATION_ENABLED`](/settings-and-features/settings/patient-registration-enabled) `true` **and** a default patient AccessPolicy on the project |
| Make patient onboarding invitation-only | [`PATIENT_REGISTRATION_ENABLED`](/settings-and-features/settings/patient-registration-enabled) `false`, and [`PATIENT_INVITATION_ENABLED`](/settings-and-features/settings/patient-invitation-enabled) as you need it. [Invitations](/settings-and-features/settings/patient-invitation-enabled) 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`](/settings-and-features/settings/default-practitioner-access-policy) first, then [`PRACTITIONER_REGISTRATION_ENABLED`](/settings-and-features/settings/practitioner-registration-enabled) `true` |
| Add practitioners by invitation instead | [`PRACTITIONER_INVITATION_ENABLED`](/settings-and-features/settings/practitioner-invitation-enabled) and [`PRACTITIONER_APP_URL`](/settings-and-features/settings/practitioner-app-url) |
| Pause patient sign-in | [`PATIENT_LOGIN_ENABLED`](/settings-and-features/settings/patient-login-enabled) `false` |
| Pause practitioner sign-in | [`PRACTITIONER_LOGIN_ENABLED`](/settings-and-features/settings/practitioner-login-enabled) `false` |
| Invite clinicians who register with a work email | [`CLINICIAN_INVITE_ON_BUSINESS_EMAIL`](/settings-and-features/settings/clinician-invite-on-business-email) `true`, a default practitioner AccessPolicy, a practitioner app URL and a patient app URL; see [business-email sign-up](/authentication/patient-registration#business-email-sign-up) |

## 4. Give new users an AccessPolicy [#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 | The text setting [`DEFAULT_PATIENT_ACCESS_POLICY`](/settings-and-features/settings/default-patient-access-policy), which must be `AccessPolicy/<id>` of a policy in **this** project. Patient registration is refused until it exists. |
| New practitioners | The text setting [`DEFAULT_PRACTITIONER_ACCESS_POLICY`](/settings-and-features/settings/default-practitioner-access-policy), which must be `AccessPolicy/<id>` of a policy in **this** project. |

Set the patient policy:

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

Set the practitioner policy:

```bash
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` ([`INVALID_SETTING_VALUE`](/errors/invalid-setting-value)).

## 5. Switch the flows on or off [#5-switch-the-flows-on-or-off]

```bash
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 [#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:

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/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 |
| --- | --- |
| `401` `Invalid email or password.` | 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`](/settings-and-features/settings/patient-login-enabled) is `false`. |

## 7. Map the emails your flows send [#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](/authentication/patient-registration) | `PATIENT_WELCOME` | The new patient gets no welcome email. |
| [Business-email sign-up](/settings-and-features/settings/clinician-invite-on-business-email) | `CLINICIAN_SIGNUP_INVITE` | The person is registered as a patient. |
| [Invitations](/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](/email-templates/set-up-email). Practitioner registration sends no email.

## Settings are checked at different moments [#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`](/settings-and-features/settings/practitioner-login-enabled) at `login/token`, not at `login/start`, and the patient sign-in checks [`PATIENT_LOGIN_ENABLED`](/settings-and-features/settings/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.

## Related [#related]

- [Access policies](/access-policies)
- [Email templates](/email-templates)
- [Settings and features](/settings-and-features)
- [Errors and troubleshooting](/authentication/troubleshooting)
