OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Tenant Authentication

Verify patient MFA code

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

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

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"  }'

Request Body

application/json
  1. body
mfaToken*string
Length6 <= length
loginId*string
Formatuuid

Response Body

A session code for login/token.

application/json
  1. response
nextStep*"token"
Value in"token"
sessionCode*string
Example Request
curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/Patient/login/mfa' \  -H 'Content-Type: application/json' \  -d '{  "mfaToken": "string",  "loginId": "8f568ecd-0198-4d41-91e2-cb501f4140f6"}'
Example Response
{  "nextStep": "token",  "sessionCode": "string"}

Exchange patient session code for tokens POST

Finishes a patient login: exchanges the session code from `login/start` (or `login/mfa`) and your PKCE `codeVerifier` for an access token and a refresh token. **Auth:** none. The session code and code verifier prove the earlier steps. ## Behaviour - Ovok redeems the code with Medplum's `oauth2/token` endpoint (`grant_type=authorization_code`). - The signed-in profile must be a Patient. A code for any other profile type is refused. - If the account was scheduled for deletion (`DELETE /auth/delete`), logging in cancels the deletion. - The response holds `accessToken`, `refreshToken`, `expiresIn` (seconds) and references to the `project` and `profile`. - Error responses are delayed to take at least one second. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/Patient/login/token' \ -H 'Content-Type: application/json' \ -d '{ "sessionCode": "<sessionCode from login/start>", "codeVerifier": "<your codeVerifier>" }' ```

Register a patient POST

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 ```bash 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" }' ```