Authentication
Sign patients and practitioners in to an Ovok project with tenant authentication, and learn which project settings control it.
Ovok signs people in per tenant: every project is a tenant, named by a short tenant code. A patient signs in to the tenant they belong to; a practitioner signs in once and then chooses a tenant. Tokens are issued for one project, so the project a user signed in to decides what they can reach.
This section covers tenant authentication: the eight routes under /v1/auth/tenant/. Use them for every new app.
How sign-in works
Sign-in uses PKCE with S256, so a code stolen in transit cannot be turned into tokens. Your app creates a random code verifier, sends its hash (the code challenge) when it starts, and sends the verifier itself when it finishes.
Registration returns tokens straight away, so a newly registered user is signed in without a second step.
The eight routes
Each audience has four routes under its own path.
None of them needs a bearer token. The tenant is named by tenantCode in the body, except for the practitioner login/start and login/mfa steps, which come before a tenant is chosen.
Carers (FHIR RelatedPerson) sign in the same way as patients, under /v1/auth/tenant/RelatedPerson/login/.... They have no register route: a carer account is made only by accepting a patient's invite.
Before you build: what the project needs
Project settings control sign-in and registration. Most default to on, but registration needs more than a switch, and practitioner registration is off until you turn it on. Set up your project walks through it.
| Flow | Settings it depends on | When unset |
|---|---|---|
| Patient sign-in | PATIENT_LOGIN_ENABLED | On |
| Patient registration | PATIENT_REGISTRATION_ENABLED, plus a default patient AccessPolicy on the project | On, but refused until the AccessPolicy exists |
| Business-email sign-up (optional) | CLINICIAN_INVITE_ON_BUSINESS_EMAIL, DEFAULT_PRACTITIONER_ACCESS_POLICY, PRACTITIONER_APP_URL, PATIENT_APP_URL | Off |
| Practitioner sign-in | PRACTITIONER_LOGIN_ENABLED | On |
| Practitioner registration | PRACTITIONER_REGISTRATION_ENABLED set to true, plus DEFAULT_PRACTITIONER_ACCESS_POLICY | Off |
| Carer sign-in | RELATED_PERSON_LOGIN_ENABLED | On |
GET /v1/project/settings reports false for a boolean that was never set, even where the flow behaves as on. See unset settings before you read that response as a switch.
A welcome email after patient registration and the invitation for business-email sign-ups are sent only when their template is mapped. Settings decide whether a flow can run, not what a signed-in user may do; see settings are not permissions.
Find your tenant code
A tenant code is a short name, such as big-health-company, that your apps send in tenantCode.
- A signed-in user can read the code of their current project with
GET /v1/organizations/code. - A practitioner's
login/startresponse lists thetenantCodeof every project they belong to. - A patient who has forgotten their code can be emailed all of theirs with
POST /v1/organizations/code/email. The route always answers202, so it does not reveal whether the address has an account.
What you get back
A finished sign-in or a registration returns:
| Field | Meaning |
|---|---|
accessToken | Bearer token for API calls. Valid for one hour. |
refreshToken | Token for renewing the session. |
expiresIn | Lifetime of the access token, in seconds. |
project | reference and display of the project the tokens are for. |
profile | reference and display of the Patient or Practitioner who signed in. |
Send the access token as Authorization: Bearer <accessToken>. To renew a session or sign out, use the account routes.
Account routes
Once a user holds tokens, account-level routes manage the account: identity, sessions, passwords, deletion and consents. They have no /v1/auth/tenant/ variants and work with the tokens a tenant sign-in or registration returns. The two password reset routes and the token refresh need no bearer token.
Identity and sessions
GET /v1/auth/me— Get account informationGET /v1/auth/session— List sessionsDELETE /v1/auth/session/:option— Revoke sessionsPOST /v1/auth/refresh-token— Refresh an access tokenPOST /v1/auth/logout— Log out
Passwords and deletion
PATCH /v2/auth/change-password— Change passwordPOST /v2/auth/reset-password— Send a password reset emailPOST /v2/auth/reset-password/process— Set a new password from a reset emailDELETE /v1/auth/delete— Schedule account deletion
Consents of the signed-in practitioner
GET /v1/me/consent/medical— Get medical consentPOST /v1/me/consent/medical— Give or withdraw the medical consentGET /v1/me/consent/legal— Get legal consentPOST /v1/me/consent/legal— Accept or withdraw the terms
Limits you will meet
Every route here is rate limited per route and client IP address. Over the limit, the answer is 429 with Retry-After in seconds, repeated in retryAfterSec. See Slim API errors for the rate-limit headers.
| Route | Requests per minute |
|---|---|
login/start | 10 |
login/token | 30 |
login/mfa | 5 |
register | 5 |
Every error response from these routes takes at least one second, which slows down guessing; a slow failure is not an outage. The error shape is in errors and troubleshooting.
Password policy
Every route that sets a password applies one rule: registration, password change, password reset, and a new carer's password on accepting a record share.
- At least 12 characters, not counting spaces at the start or end, and at most 128.
- Not a common password. Ovok compares the password, trimmed and lower-cased, with passwords of 12 or more characters from public breach lists.
A password that breaks the rule answers 422. Its entry in errors names the field (password or newPassword) and one of these codes:
| Code | Meaning |
|---|---|
FIELD_TOO_SHORT | Fewer than 12 characters once leading and trailing spaces are removed. |
FIELD_TOO_LONG | More than 128 characters. |
PASSWORD_TOO_COMMON | The password is on the common-password list. |
Where to go next
- Set up your project: tenant code, settings and AccessPolicies.
- Patient sign-in and practitioner sign-in.
- Patient registration and practitioner registration.
- Errors and troubleshooting.
- Account routes: sessions, passwords, deletion and consents once a user is signed in.
Last updated on