Reset Password

This guide explains how to build a password reset flow for patients using the CarePortals Patient API. The process begins when a patient requests a password reset link, continues with token validation, and concludes when they have successfully set a new password.

Flow Overview

The password reset flow is a three-step process that allows a patient to securely reset their password after verifying their identity via an email link.

Request a Reset Token: The patient provides their email to initiate the process and receive a reset token.
Validate the Reset Token: The application validates the token received from the email link to ensure it's authentic before allowing the password to be changed.
Submit the New Password: The patient provides a new password, which is submitted along with the validated token to complete the process.

Step 1: Request a Password Reset Token

To begin the flow, you must request a password reset token. To do this, call the Request Password Reset Token endpoint with a POST request. In the request body, you must include the patient's email, and you may also provide your organization id (<ORG_ID>) as a header. This action triggers the system to send an email to the patient containing a unique link with the token needed for the next step.

📘
The <ORG_ID> isn't a mandatory parameter since we obtain it from the domain itself. However, if you're hosting your site in a separate domain (other than the patient portal), then an organization ID is required in the request header.

curl -X POST 'https://patient-api.portals.care/auth/forgot' \
--header 'Content-Type: application/json' \
--header 'organization: <ORG_ID>' \
--data '{
  "email": "[email protected]"
}

true

Step 2: Validate the Reset Token

After the patient clicks the link in their email, your application must verify that the token is valid. To do this, call the Validate Password Reset Token endpoint with a GET request. In your request, you must include the token from the email link as a query parameter and your organization ID (<ORG_ID>) as a header.

curl -X GET 'https://patient-api.portals.care/auth/reset?token=a1b2c3d4e5f61234' \
--header 'organization: <ORG_ID>'

{
  "_id": "67d5e4a1b8c7d9f3a1b2c3d4",
  "uname": "[email protected]#appgen_demo",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "salt": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "hash": "$2b$10$abcdefghijklmnopqrstuv.abcdefghijklmnopqrstuv.abcdefghijkl",
  "provinceCode": "NY",
  "phone": "+12125551234",
  "stripeId": "cus_AbcDef12345678",
  "bigcommerceId": "98765",
  "referrer": "FRIEND10",
  "iat": "1725897221",
  "exp": "1725983621",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNzI1ODk3MjIxfQ.abcdef123456",
  "age": 35,
  "isInsuranceAvailable": false,
  "identifiers": [
    {
      "hcNum": "1234-567-890-AB",
      "hcVer": "AB",
      "type": "OHIP",
      "uid": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
      "effectiveDate": "2023-01-01T00:00:00.000Z",
      "expiryDate": "2028-12-31T23:59:59.000Z"
    }
  ],
  "organization": "appgen_demo",
  "dob": "1990-05-15",
  "addresses": [
    {
      "company": "",
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "New York",
      "provinceCode": "NY",
      "countryCode": "US",
      "postalCode": "10001"
    }
  ],
  "defaultAddress": {
    "company": "",
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "New York",
    "provinceCode": "NY",
    "countryCode": "US",
    "postalCode": "10001"
  },
  "tags": "new_patient",
  "currency": "USD",
  "notificationsCount": 2,
  "contactPreference": {
    "email": true
  },
  "watchlist": [
    "finasteride"
  ],
  "usedCoupons": [
    "WELCOME10"
  ],
  "meta": {
    "gender": "male",
    "allergies": "Penicillin",
    "weight": 180,
    "temperature": 98.6
  },
  "createdAt": "2025-09-09T17:34:12.013Z",
  "conversationId": "conv_xyz789",
  "assignedQuestionnaires": [
    "facesheet_v2"
  ],
  "providers": [
    "provider_id_12345"
  ],
  "groups": [
    "test_group_a"
  ],
  "verifications": {
    "email": "verified"
  },
  "passwordReset": {
    "code": "a1b2c3d4e5f6",
    "expiry": 1725900821
  },
  "gender": "male",
  "extras": {
    "dosespotId": "98765432"
  }
}

A successful response confirms the token is valid, and you can proceed to display a form for the user to enter their new password.

Step 3: Submit the New Password

The final step is to set the new password. To do this, call the Reset Patient Password endpoint with a POST request. In the request body, you must include the validated token and the user's new password.

curl -X POST 'https://patient-api.portals.care/auth/reset' \
--header 'Content-Type: application/json' \
--header 'organization: <ORG_ID>' \
--data '{
  "token": "a1b2c3d4e5f61234",
  "password": "a-very-secure-new-password"
}'

{
  "status": "success",
  "data": {
    "username": "[email protected]#appgen_demo"
  }
}