OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Tenant Authentication

Register a patient

  • Sandbox: available
  • Staging: available
  • Production: unknown
POST
/auth/tenant/Patient/register

Registers a new patient account in a tenant and returns its tokens, so the user is signed in straight away. On some projects a business email address gets a clinician invite instead.

Auth: none. The tenant is named by tenantCode. Scope: the project that owns tenantCode.

Behaviour

  • Registration needs a default patient access policy on the project, and PATIENT_REGISTRATION_ENABLED must not be false (it defaults to on). The new membership gets that access policy.
  • The password must have at least 12 characters, not counting spaces at either end, and must not be on Ovok's list of common and breached passwords. Any character is allowed and none is required. A refused password answers 422 with the error on password.
  • An email that already has a Patient account in this project is refused.
  • Clinician invite. When the project setting CLINICIAN_INVITE_ON_BUSINESS_EMAIL is on and the address is a business address (not free-mail or disposable), no patient is created. Ovok creates a practitioner account with the project's default practitioner access policy, emails a CLINICIAN_SIGNUP_INVITE with a set-password link, and answers { "nextStep": "clinician-invite" } (no tokens). If the invite cannot go out (no default practitioner policy, no practitioner app URL, the email fails), a patient is registered as usual.
  • The invite email carries a "continue as patient" link with a continueAsPatientToken. Send that token here to register as a patient anyway. It is valid for 7 days and only for the same email and project.
  • On success a PATIENT_WELCOME email is sent in the background. The response does not wait for it.
  • Error responses are delayed to take at least one second.

Example

curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/Patient/register' \  -H 'Content-Type: application/json' \  -d '{    "email": "max.mustermann@example.com",    "password": "your-password",    "name": "Max",    "surname": "Mustermann",    "tenantCode": "my-medical-project"  }'

Request Body

application/json
  1. body
email*string
Formatemail
password*string
Length12 <= length <= 128
name*string
surname*string
tenantCode*string
continueAsPatientToken?string

Response Body

Access token, refresh token, expiry, project and profile, or { nextStep: "clinician-invite" }.

application/json
  1. response
accessToken*string

Bearer access token. Expires in 1 hour.

refreshToken?string

Refresh token.

expiresIn?integer

Token expiration.

Default3600
project*
profile*
Example Request
curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/Patient/register' \  -H 'Content-Type: application/json' \  -d '{  "email": "user@example.com",  "password": "stringstring",  "name": "string",  "surname": "string",  "tenantCode": "string"}'
Example Response
{  "accessToken": "string",  "refreshToken": "string",  "expiresIn": 3600,  "project": {    "reference": "string",    "display": "string"  },  "profile": {    "reference": "string",    "display": "string"  }}

Verify patient MFA code POST

Verifies the TOTP code of a patient who has MFA enrolled, after `login/start` answered `nextStep: "mfa"`. Returns the session code for `login/token`. **Auth:** none. The `loginId` from `login/start` identifies the login. ## Behaviour - `mfaToken` must equal the current TOTP code generated from the user's MFA secret. - On success the login is marked MFA-verified and the response is `{ "nextStep": "token", "sessionCode": ... }`. Pass `sessionCode` to `POST /auth/tenant/Patient/login/token`. - Error responses are delayed to take at least one second. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/Patient/login/mfa' \ -H 'Content-Type: application/json' \ -d '{ "loginId": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "mfaToken": "123456" }' ```

Start related person login POST

Starts a related person (carer) login for one tenant: checks the email and password and returns either a session code to exchange for tokens or, when the user has MFA enrolled, a login ID for the MFA step. **Auth:** none. The tenant is named by `tenantCode`. **Scope:** the project that owns `tenantCode`. ## Behaviour - This is step 1 of a PKCE login. Generate a random `codeVerifier`, send its S256 hash as `codeChallenge` here, and send the `codeVerifier` itself to `POST /auth/tenant/RelatedPerson/login/token`. - The account must be a RelatedPerson of the tenant's project. A carer account is made only by accepting a record-share invite (`POST /v1/invites/record-share/accept`); there is no register route. A Patient or Practitioner with the same email cannot log in here. - `RELATED_PERSON_LOGIN_ENABLED` on the project must not be `false` (it defaults to on). It is the carers' own switch: `PATIENT_LOGIN_ENABLED` does not apply to them. - Response `nextStep`: - `token`: no MFA. Pass `sessionCode` to `login/token`. - `mfa`: the user has MFA enrolled. Pass `loginId` and the current TOTP code to `POST /auth/tenant/RelatedPerson/login/mfa`. - A wrong email, an unknown account, an account without a password and a wrong password all give the same 401 `Invalid email or password.` - After 5 failed sign-ins for one email within 15 minutes, that email's sign-ins answer 429 with `Retry-After` for 15 minutes, the right password included, whether or not the email has an account. A successful sign-in resets the count. - A forgotten password is reset through `POST /v2/auth/reset-password` with `"type": "RelatedPerson"` and the app's `clientId`. - Error responses are delayed to take at least one second. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/RelatedPerson/login/start' \ -H 'Content-Type: application/json' \ -d '{ "email": "max.mustermann@example.com", "password": "your-password", "tenantCode": "my-medical-project", "codeChallenge": "<base64url S256 hash of your codeVerifier>" }' ```