Send a password reset email

Method	Path
POST	/v2/auth/reset-password

Authentication · Account routes · Email templates

Sends a password reset email to a patient or a practitioner. The answer is the same whether or not an account exists, so the route cannot be used to find out which addresses are registered. The second step is Set a new password from a reset email.

note

This is an account-level route. It has no /auth/tenant/ variant and needs no token. Use it for patients and practitioners of any tenant.

Auth: None. Scope: For a patient, the project that owns clientId. For a practitioner, the account is found by email across projects.

Request

Body

Name	Type	Required	Description
email	string (email)	Yes	Address of the account. Ovok lowercases it.
type	"Patient" | "Practitioner"	Yes	Kind of account.
clientId	string	Patients only	The id of the client application that identifies your patient app to Ovok. It selects the project the patient belongs to. Ignored when type is Practitioner.

Behaviour

• The answer 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, accounts that cannot be emailed, and accounts that exist.
• When the account exists, Ovok creates a reset request and emails the user. A new request replaces any earlier open one for the same user, so only the newest link works.
• Patients get the PATIENT_RESET_PASSWORD template and practitioners the RESET_PASSWORD template. The email goes out only when its template is mapped. See the template catalogue.
• The email carries a link <app URL>/setpassword/<id>/<secret> and the request id and secret as template parameters. The app URL is the project's patient app URL or practitioner app URL. If none is set, the request's Origin is used when it is an allowed one.
• A practitioner who belongs to more than one project gets a link to the Ovok platform app, never to one project's app.
• 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 the second step.
• If a practitioner has several accounts, the first one found is used.
• The route is rate limited to 5 requests per minute for each caller.

Example

curl -X POST 'https://api.sandbox.ovok.com/v2/auth/reset-password' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alex@example.com",
    "type": "Patient",
    "clientId": "7e3a9d52-1c6b-4f08-a5d4-b2e8c0f19a37"
  }'

For a practitioner, send no clientId:

curl -X POST 'https://api.sandbox.ovok.com/v2/auth/reset-password' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "dr.smith@example.com",
    "type": "Practitioner"
  }'

Successful response

201 — Always the same body.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "details": {
        "text": "If the user exists, a password reset email has been sent."
      }
    }
  ]
}

Field	Type	Description
resourceType	"OperationOutcome"	Always OperationOutcome.
issue[].severity	"information"	Always information.
issue[].code	"informational"	Always informational.
issue[].details.text	string	The neutral confirmation message. Show it, or your own text, whatever the account state.

Errors

Status	Meaning
422	email is not a valid address, type is not Patient or Practitioner, or type is Patient and clientId is missing.
429	More than 5 requests in a minute from the same caller.