OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Tenant Authentication

Exchange related person session code for tokens

  • Sandbox: available
  • Staging: available
  • Production: unknown
POST
/auth/tenant/RelatedPerson/login/token

Finishes a related person (carer) 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 RelatedPerson. A code for any other profile type is refused.
  • The token reads only what patients have shared with the carer: the shared Observation codes and each sharer's record with its contact fields hidden. Practitioner and patient-only routes refuse it with 403.
  • 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

curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/RelatedPerson/login/token' \  -H 'Content-Type: application/json' \  -d '{    "sessionCode": "<sessionCode from login/start>",    "codeVerifier": "<your codeVerifier>"  }'

Request Body

application/json
  1. body
sessionCode*string
codeVerifier*string

Response Body

Access token, refresh token, expiry, project and profile.

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/RelatedPerson/login/token' \  -H 'Content-Type: application/json' \  -d '{  "sessionCode": "string",  "codeVerifier": "string"}'
Example Response
{  "accessToken": "string",  "refreshToken": "string",  "expiresIn": 3600,  "project": {    "reference": "string",    "display": "string"  },  "profile": {    "reference": "string",    "display": "string"  }}

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

Verify related person MFA code POST

Verifies the TOTP code of a related person (carer) 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/RelatedPerson/login/token`. - Error responses are delayed to take at least one second. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/auth/tenant/RelatedPerson/login/mfa' \ -H 'Content-Type: application/json' \ -d '{ "loginId": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "mfaToken": "123456" }' ```