OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Reset Password

Send reset password email

  • Sandbox: available
  • Staging: available
  • Production: unknown
POST
/v2/auth/reset-password

Sends a password reset email to a Patient, a RelatedPerson (carer) or a Practitioner. The answer is the same whether or not an account exists, so the route cannot be used to find out which emails are registered.

Auth: none. Scope: for a Patient or RelatedPerson, the project that owns clientId. For a Practitioner, the account is found by email across projects.

Behaviour

  • type is Patient, RelatedPerson or Practitioner. clientId is required when type is Patient or RelatedPerson and is ignored for a Practitioner.
  • The response is always a FHIR OperationOutcome saying "If the user exists, a password reset email has been sent." It is returned for unknown emails, unknown client IDs and accounts that could not be mailed.
  • When the account exists, Ovok creates a reset request, which replaces any earlier open reset request for the user, and emails the user. Patients and RelatedPersons get the PATIENT_RESET_PASSWORD template and Practitioners the RESET_PASSWORD template.
  • The email carries a link <app URL>/setpassword/<id>/<secret> plus the request id and secret. The app URL is the project's patient app URL for a Patient or RelatedPerson, and its practitioner app URL for a Practitioner; if none is set, the request's Origin is used when it is an allowed one.
  • A Practitioner who is a member of more than one project gets a link to the Ovok platform app instead of a project's app URL.
  • If no app URL can be found, the email still goes out, without a link. The id and secret in it can be sent to POST /v2/auth/reset-password/process.
  • If a Practitioner has several accounts, the first one found is used.

Example

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

Request Body

application/json
  1. body
email*string

Email address.

Formatemail
clientId?string

Client ID. Required for patients and related persons.

type*string

The type of the user.

Value in"Patient""RelatedPerson""Practitioner"

Response Body

Reset password outcome.

application/json
  1. response
resourceType?string
Default"OperationOutcome"
issue*array<>
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v2/auth/reset-password' \  -H 'Content-Type: application/json' \  -d '{  "email": "max.mustermann@example.com",  "clientId": "a703da46-ec97-a84a-4573-c50634706367",  "type": "Patient"}'
Example Response
{  "resourceType": "OperationOutcome",  "issue": [    {      "severity": "fatal",      "code": "invalid",      "details": {        "text": "string"      }    }  ]}

Delete public resource token DELETE

Removes the public token from a resource, so it can no longer be read with `GET /public/{token}`. The resource itself is kept. **Auth:** bearer token of a project admin. ## Behaviour - The resource must be in the caller's project or one of its sub-projects. A resource of any other project, the parent project included, answers `403` and is left unchanged; an unknown id answers `404`. - Removes the `meta.extension` entry with the URL `https://api.ovok.com/fhir/StructureDefinition/public-resource-token`. Other extensions are kept. - Calling it on a resource without a token succeeds. - The response is `{ token: null, resource }` with the updated resource. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/public/DocumentReference/87ea5dfc-8b8e-384d-8489-79496e706390' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Reset user password with the information from the email. POST

Sets a new password using the `id` and `secret` from a reset email. Use it when your app handles the reset itself instead of sending the user to the emailed link. **Auth:** none. The reset request `id` and `secret` are the credential. ## Behaviour - The `id` and `secret` come from the email sent by `POST /v2/auth/reset-password`. The `password` is the new password. - 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 invite link (from `POST /auth/invite` or a practitioner invite) sets a password for 7 days after it was sent. After that it answers 410 `This invite link has expired. Ask for a new invite.`, and inviting the user again sends a fresh link. Reset links are not limited this way. - A request can be used once. Ovok marks it used before it changes the password, so a request whose password change then fails cannot be retried and the user must ask for a new email. - Setting the password also marks the user's email as verified, because the secret came by email. - The response is a minimal `User` with `resourceType`, `id` and `email`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v2/auth/reset-password/process' \ -H 'Content-Type: application/json' \ -d '{ "id": "c3499c27-2973-0a7f-807e-fb8676a92dcb", "secret": "k3J9xQ2mV7", "password": "Ex4mple-Passw0rd" }' ```