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.

FlowSettings it depends onWhen unset
Patient sign-inPATIENT_LOGIN_ENABLEDOn
Patient registrationPATIENT_REGISTRATION_ENABLED, plus a default patient AccessPolicy on the projectOn, 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_URLOff
Practitioner sign-inPRACTITIONER_LOGIN_ENABLEDOn
Practitioner registrationPRACTITIONER_REGISTRATION_ENABLED set to true, plus DEFAULT_PRACTITIONER_ACCESS_POLICYOff
Carer sign-inRELATED_PERSON_LOGIN_ENABLEDOn

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/start response lists the tenantCode of 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 answers 202, so it does not reveal whether the address has an account.

What you get back

A finished sign-in or a registration returns:

FieldMeaning
accessTokenBearer token for API calls. Valid for one hour.
refreshTokenToken for renewing the session.
expiresInLifetime of the access token, in seconds.
projectreference and display of the project the tokens are for.
profilereference 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

Passwords and deletion

Consents of the signed-in practitioner

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.

RouteRequests per minute
login/start10
login/token30
login/mfa5
register5

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:

CodeMeaning
FIELD_TOO_SHORTFewer than 12 characters once leading and trailing spaces are removed.
FIELD_TOO_LONGMore than 128 characters.
PASSWORD_TOO_COMMONThe password is on the common-password list.

Where to go next

  1. Set up your project: tenant code, settings and AccessPolicies.
  2. Patient sign-in and practitioner sign-in.
  3. Patient registration and practitioner registration.
  4. Errors and troubleshooting.
  5. Account routes: sessions, passwords, deletion and consents once a user is signed in.

Last updated on

On this page