OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Authentication

Login

  • Sandbox: available
  • Staging: available
  • Production: unknown
POST
/v2/auth/login

Signs a user in with email and password for the project that owns a client application, and returns an access token and a refresh token. New integrations should use the tenant login routes (/auth/tenant/Patient/login/start and /auth/tenant/Practitioner/login/start) instead.

Auth: none. The email and password are the credential, and clientId names the project. Scope: the project that owns the ClientApplication with the given clientId.

Behaviour

  • Ovok looks up the account by email in the client application's project. If a Patient and a Practitioner share the email in that project, one of them is picked and which one is not defined.
  • The account type's login switch must be on: the project setting PATIENT_LOGIN_ENABLED or PRACTITIONER_LOGIN_ENABLED. Both default to on. It is checked once the password is right, so its 403 never tells which emails have an account.
  • A wrong password and an unknown email give the same 401 Invalid email or password., so the response does not tell you which one was wrong. An unknown clientId gives a 400.
  • 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.
  • If Medplum's own login rate limit is hit, you get a 429 instead of a 401. Wait and retry.
  • Callers without a token may send at most 10 requests per minute from one IP address.
  • A successful login cancels a pending account deletion (DELETE /auth/delete).
  • This route has no MFA step. Use the tenant login routes for users with MFA enrolled.
  • The access token lasts one hour (expiresIn is in seconds). Use POST /auth/refresh-token to renew it.

Example

curl -X POST 'https://api.sandbox.ovok.com/v2/auth/login' \  -H 'Content-Type: application/json' \  -d '{    "email": "max.mustermann@example.com",    "password": "Ex4mple-Passw0rd",    "clientId": "c3499c27-2973-0a7f-807e-fb8676a92dcb"  }'

Request Body

application/json
  1. body
email*string

The user's email address.

Formatemail
password*string

The user's password.

Length1 <= length <= 128
clientId*string

The client ID from the ClientApplication resource.

Formatuuid

Response Body

Access token, refresh token and expiration time.

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/v2/auth/login' \  -H 'Content-Type: application/json' \  -d '{  "email": "user@example.com",  "password": "string",  "clientId": "5e505642-9024-474d-9434-e5a44f505cc5"}'
Example Response
{  "accessToken": "string",  "refreshToken": "string",  "expiresIn": 3600,  "project": {    "reference": "string",    "display": "string"  },  "profile": {    "reference": "string",    "display": "string"  }}

Schedule user account deletion DELETE

Schedules deletion of the caller's own account. The account is not deleted right away: it stays until the scheduled date, and signing in again before then cancels the deletion. **Auth:** bearer token of the user who deletes their own account. **Scope:** the caller's own User, in the project of the token. ## Behaviour - `days` (0 to 90, default 30) sets how many days from now the account is due. `wipe` (default `false`) is recorded on the request. - Ovok signs the user out of all sessions, then records the deletion date on the User. Calling the route again resets the date. - A job runs every day at midnight. For each User whose date has passed, it deletes the project membership, the profile (Patient or Practitioner) and the User. - The job does not purge medical data yet, so `wipe` has no effect on what is deleted. - Ovok sends a confirmation email (`PATIENT_ACCOUNT_DELETION` for a Patient, `ACCOUNT_DELETION` otherwise). A failed email does not fail the request. - A successful login on the account (`POST /v2/auth/login`, or the tenant login routes) removes the scheduled deletion. - The response holds `scheduled` (the due date, ISO 8601) and the updated `user`, without its password hash. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/auth/delete' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "days": 30, "wipe": false }' ```

Get account information GET

Returns the signed-in user's context: project, membership, profile, user configuration, access policy and security details such as MFA status and sessions. Call it after sign-in to learn who the token belongs to. **Auth:** bearer token. A missing, non-bearer or invalid token gives 401. **Scope:** the project of the token. ## Behaviour - The answer is Medplum's `auth/me` for the token's session. - The call always discards Ovok's cached copy of this session's profile and reads a fresh one, so changes to the profile or access policy show up in the response and in later requests with the same token. - Use the returned `profile.resourceType` to tell Patients from Practitioners. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/auth/me' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```