---
title: Send a password reset email
sidebar_label: Send a password reset email
sidebar_position: 7
description: Email a patient or practitioner a password reset link with POST /v2/auth/reset-password, without revealing whether the account exists.
---

# Send a password reset email

| Method | Path |
| --- | --- |
| `POST` | `/v2/auth/reset-password` |

[Authentication](/authentication) · [Account routes](/authentication#account-routes) · [Email templates](/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](/authentication/account/process-password-reset).

:::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](/email-templates/map-templates). See the [template catalogue](/email-templates/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](/settings-and-features/settings/patient-app-url) or [practitioner app URL](/settings-and-features/settings/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](/authentication/account/process-password-reset).
- 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

```bash
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`:

```bash
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.

```json
{
  "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. |