> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digiflecttech.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Change or Reset a Save App Account Password Securely

> Change your current password while authenticated, or reset a forgotten password by verifying your phone number through Firebase Phone Authentication.

Save App provides two password management flows: an authenticated change-password endpoint for users who know their current password, and an unauthenticated reset flow for users who have forgotten it. The reset flow relies on Firebase Phone Authentication to verify identity on the client before calling the backend.

## POST /api/auth/change-password

Changes the password for the currently authenticated user. Requires a valid Bearer token in the `Authorization` header.

<Note>
  This endpoint is rate-limited to **5 requests per minute**.
</Note>

### Request headers

<ParamField header="Authorization" type="string" required>
  `Bearer <token>` — the JWT token returned at login.
</ParamField>

### Request body

<ParamField body="currentPassword" type="string" required>
  The user's existing password. Minimum 8 characters. The server verifies this against the stored hash before making any change.
</ParamField>

<ParamField body="newPassword" type="string" required>
  The user's desired new password. Minimum 8 characters.
</ParamField>

### Response

<ResponseField name="success" type="boolean" required>
  `true` when the password was changed successfully.
</ResponseField>

<ResponseField name="message" type="string" required>
  A human-readable confirmation message.
</ResponseField>

### Error responses

| Status             | Condition                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid Bearer token, or `currentPassword` does not match the stored password. |

### Example

<CodeGroup>
  ```bash Change password theme={null}
  curl --request POST \
    --url https://api.saveapp.co/api/auth/change-password \
    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    --header 'Content-Type: application/json' \
    --data '{
      "currentPassword": "oldpassword1",
      "newPassword": "newpassword2"
    }'
  ```
</CodeGroup>

```json theme={null}
{
  "success": true,
  "message": "Password changed successfully"
}
```

***

## Password reset flow

Use this flow when the user cannot log in because they have forgotten their password. The client must first verify the user's phone number using Firebase Phone Authentication before calling the backend reset endpoint.

<Note>
  `POST /api/auth/forgot-password` is **deprecated** and no longer sends OTPs or emails. Use Firebase Phone Authentication on the client side to verify the user's identity, then call `POST /api/auth/reset-password` directly.
</Note>

### Step 1 — Verify phone on the client

Use the Firebase SDK in your mobile or web application to send a verification code to the user's phone and confirm the code. Once the user successfully verifies, proceed to step 2.

### Step 2 — POST /api/auth/reset-password

Resets the password for the account associated with the given phone number. This endpoint is rate-limited to **2 requests per minute**.

<Warning>
  There is no server-side check that Firebase verification was completed before calling this endpoint. Implement the Firebase verification step on your client to protect your users from unauthorised password resets.
</Warning>

#### Request body

<ParamField body="phone" type="string" required>
  The phone number of the account to reset, in Uganda format (`+256XXXXXXXXX`).
</ParamField>

<ParamField body="newPassword" type="string" required>
  The user's new password. Minimum 8 characters.
</ParamField>

#### Response

<ResponseField name="success" type="boolean" required>
  `true` when the password was reset successfully.
</ResponseField>

<ResponseField name="message" type="string" required>
  A human-readable confirmation message.
</ResponseField>

#### Error responses

| Status          | Condition                                    |
| --------------- | -------------------------------------------- |
| `404 Not Found` | No account found for the given phone number. |

#### Example

<CodeGroup>
  ```bash Reset password theme={null}
  curl --request POST \
    --url https://api.saveapp.co/api/auth/reset-password \
    --header 'Content-Type: application/json' \
    --data '{
      "phone": "+256700123456",
      "newPassword": "resetpassword3"
    }'
  ```
</CodeGroup>

```json theme={null}
{
  "success": true,
  "message": "Password reset successfully"
}
```

***

## POST /api/auth/verify-reset-otp

Verifies a one-time passcode for the `reset_password` purpose against the OTP table. This endpoint is a legacy mechanism from before the Firebase Phone Auth migration.

<Warning>
  This endpoint is part of the legacy OTP-based reset flow. For new integrations, use `POST /api/auth/reset-password` directly after completing Firebase Phone Authentication on the client. Do not build new features that depend on this endpoint.
</Warning>

### Request body

<ParamField body="phone" type="string" required>
  The phone number associated with the OTP record.
</ParamField>

<ParamField body="otp" type="string" required>
  The OTP code to verify.
</ParamField>

### Response

Returns `{"success": true, "message": "OTP verified successfully"}` on success, or `400 Bad Request` if the OTP is invalid or expired.