Skip to main content
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.
This endpoint is rate-limited to 5 requests per minute.

​
Request headers

​
string
required
Bearer <token> — the JWT token returned at login.

​
Request body

​
string
required
The user’s existing password. Minimum 8 characters. The server verifies this against the stored hash before making any change.
​
string
required
The user’s desired new password. Minimum 8 characters.

​
Response

​
boolean
required
true when the password was changed successfully.
​
string
required
A human-readable confirmation message.

​
Error responses

​
Example

​
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.
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.

​
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.
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.

​
Request body

​
string
required
The phone number of the account to reset, in Uganda format (+256XXXXXXXXX).
​
string
required
The user’s new password. Minimum 8 characters.

​
Response

​
boolean
required
true when the password was reset successfully.
​
string
required
A human-readable confirmation message.

​
Error responses

​
Example

​
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.
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.

​
Request body

​
string
required
The phone number associated with the OTP record.
​
string
required
The OTP code to verify.

​
Response

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