> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/account/password-reset.md).

# Password reset

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/password-reset.md).
{% endhint %}

People who forget their **password** ask for a **reset link** by email or SMS, or for a one-time code that signs them in straight away without changing the password. The reset link opens a page where they choose a new password. A **temporary password** is a flag on the account: the password still works to sign in, but the mobile apps then ask for a new one before anything else. Older mobile screens can still send a new password by email or text instead of a link.

## Rules

### Asking for a reset

* [Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md) has the same parts on all platforms: an email or phone switch, the contact field, "Send Password Reset Link", a one-time code button, and a row to resend a verification link for unverified contacts ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#layout)).
* The contact typed on [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md) carries over ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#inputs)).
* The screen checks the contact before it sends anything, so an address that is not in Snapfix gets the server's "invalid user" and nothing is sent. The web and iOS show that English text in the alert ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#actions)).
* If more than one account has the same email or phone, the server answers "Duplicate Email." or "Duplicate Mobile." and sends nothing (php-apis @ aee9175122, `htmlphp/api/snapfix/class/class.functions.php:11965-11970`).

### The reset link

* "Send Password Reset Link" sends the link to the email address, or by SMS to the phone number, and shows "A password reset link has been sent to: …" before going back to sign-in ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#actions)).
* The server sends the link to any account that has the contact, whether or not the contact is verified. Only the web hides the button until the contact is verified \[[ASK-29](https://github.com/snapfix/docs/blob/main/ASK.md#ask-29-how-should-forgot-password-treat-an-unverified-email-or-phone)] ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#platform-differences)).
* Each request creates a new link. Older links are not cancelled (`class.functions.php:11995-12051`).
* The link opens through [Deep link](https://docs.snapfix.com/how-the-apps-work/screens/account/deep-link.md) and [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md) before the password page ([Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md)).
* A reset link works for 15 minutes after it was created; after that it is refused as "reference expired" (authpy @ 5d5758661c, `model/feature_token_ops.py:3586-3588`).
* A link opened by a person who is already signed in is refused as "invalid reference" (`feature_token_ops.py:3583-3585`). The web sends signed-in people to Fix ([Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md#states)).
* Opening the link marks the account as having a temporary password. The password itself does not change until a new one is saved (`feature_token_ops.py:3595`).
* A used link is refused. The web counts the link as used when it saves the new password. The apps' save call does not, so within its 15 minutes a link used in the app opens again (`feature_token_ops.py:3589-3590`; `cognito.functions.php:1202-1206`).
* The server only lets a link set the password of the account it was issued for ("You are not allowed to change someone's password", `cognito.functions.php:1096`, `:1160`).

### One-time code instead of a link

* The code button needs a verified contact. The web offers it only for a verified contact; iOS and Android check the contact first. A verified contact gets a code and [Forgot password code](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password-code.md) ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#actions)).
* The code step works like the one on sign-in: six digits, valid for five minutes, and "Resend" after 30 seconds. Verifying signs the person in and opens Fix (web) or the data download (apps) ([Forgot password code](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password-code.md#actions)). The code rules are in [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md#one-time-code).
* The apps have a choice of SMS or WhatsApp for phone codes, but it is switched off in both builds by a constant, so only SMS shows (android @ 86068bfeea, `OtpChannelUtils.kt:21`; ios @ aa31967ac8, `SVProgressHUD/TestingConstants.swift:25`). The web's version of the choice is commented out \[[ASK-34](https://github.com/snapfix/docs/blob/main/ASK.md#ask-34-is-whatsapp-delivery-of-one-time-codes-meant-to-ship)].
* Unverified contacts see "Email not verified." and a link that sends a verification link instead, through the same reset request \[[ASK-29](https://github.com/snapfix/docs/blob/main/ASK.md#ask-29-how-should-forgot-password-treat-an-unverified-email-or-phone)] ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#actions)).

### The new password

* [Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md) asks for "New password" and "Confirm password", with a list of the rules: at least 8 characters, with a number, an uppercase letter and a lowercase letter. The web and iOS keep the save button off until it passes ([Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md#inputs)).
* Android lists the rules, but nothing enforces them on this page: the button turns on as soon as the two fields match, and the rule check has an empty body (`ResetPasswordSetNewPasswordActivity.kt:130-147`, `:263-269`).
* The server does not check these rules on the reset and invitation calls. It accepts any password that is not blank (`cognito.functions.php:1084-1090`, `:1148-1152`).
* A mismatch shows "Passwords do not match" on the web and "Passwords do not match." on Android; iOS keeps the button off ([Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md#inputs)).
* Saving a new password clears the temporary-password flag (`cognito.functions.php:1118`, `:1181`).
* After saving, the web signs the person in and opens Fix, or shows "Password reset successful" and opens sign-in when it has no stored session. The apps verify a code first when the account needs it, then open the data download ([Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md#actions)).
* The apps' save call also writes the new password to the log table (`cognito.functions.php:1122-1124`).

### Temporary passwords

* The apps show [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md) at launch or sign-in when the flag is set. It has no back or skip. Android also shows it from several screens when the flag is found later ([Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md#platform-differences)).
* Android labels the button "Complete Registration" during registration ([Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md#platform-differences)).
* The web has no Set password screen. While the flag is set, the server answers 428 to newer app builds for every call except password updates, codes and provider sign-ins, and the web opens its create-password dialog when a call answers 428. The version check behind this fails for builds from 6.11.0 ([Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md#accounts-that-need-a-step-first)).
* `temp_password` 1 means the person must set a new password before going on. With `temp_password_required` 0 as well, the sign-in check hands out tokens without a password; opening a reset link sets this pair, and saving a new password sets `temp_password` back to 0.

### Legacy reset

* [Forgot password (legacy)](https://docs.snapfix.com/how-the-apps-work/screens/account/legacy-reset.md) replaces the password with a new six-character password and sends it by email or text in plain text. The old password stops working at once (`class.functions.php:11846-11870`). Success shows "A temporary password has been sent to: …".
* iOS reaches the legacy screen from the sign-up alerts, and Android from the sign-up dialog. Neither links it from the current sign-in screen ([Forgot password (legacy)](https://docs.snapfix.com/how-the-apps-work/screens/account/legacy-reset.md#platform-differences)).
* On iOS and Android, a wrong current password in [Profile and settings](https://docs.snapfix.com/product/features/account/profile.md) offers the same reset by text or email.
* Both apps send the staff-username reset to a malformed address, so the request fails.

## Flow

```mermaid
flowchart TD
  forgot["Forgot password page"] --> contact["Enter email or phone"]
  contact --> found{"Account found?"}
  found -- no --> notfound["Server message: invalid user"]
  found -- yes --> choice{"Link or code?"}
  choice -- "link" --> sent["Link sent by email or SMS, back to sign in"]
  sent --> open["Person opens the link"]
  open --> fresh{"Within 15 minutes, not used, not signed in?"}
  fresh -- no --> err["Error on account access, then sign-in"]
  fresh -- yes --> marked["Account marked temporary"]
  marked --> newpw["Choose a new password"]
  newpw --> done["Saved: signed in (web), or the data download (apps)"]
  choice -- "code (verified contact)" --> codescreen["Code screen"]
  codescreen --> signedin["Signed in, password unchanged"]
  launch["Temporary password found at launch or sign-in (apps)"] --> setpw["Set password"]
  setpw --> done
```

## Platforms

| Capability                              | Web                                                                                                                                    | iOS                                                                                        | Android                                                                                    |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Reset link by email or SMS              | yes                                                                                                                                    | yes                                                                                        | yes                                                                                        |
| Send button only for a verified contact | yes \[[ASK-29](https://github.com/snapfix/docs/blob/main/ASK.md#ask-29-how-should-forgot-password-treat-an-unverified-email-or-phone)] | no                                                                                         | no                                                                                         |
| One-time code instead of a link         | yes, verified contacts only                                                                                                            | yes                                                                                        | yes                                                                                        |
| WhatsApp codes                          | no                                                                                                                                     | off in the current build                                                                   | off in the current build                                                                   |
| New password rules enforced             | yes                                                                                                                                    | yes                                                                                        | no                                                                                         |
| Temporary password                      | create-password dialog, when the server answers 428                                                                                    | [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md) | [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md) |
| Legacy reset by a new password          | no                                                                                                                                     | yes, from the sign-up alerts and the profile                                               | yes, from the sign-up dialog and the profile                                               |
| Staff-username reset                    | no                                                                                                                                     | fails                                                                                      | fails                                                                                      |

## Screens

* [Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md)
* [Forgot password code](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password-code.md)
* [Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md)
* [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md)
* [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md) (apps)
* [Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md): the same kind of new-password page for invited users ([Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md))
* [Forgot password (legacy)](https://docs.snapfix.com/how-the-apps-work/screens/account/legacy-reset.md) (apps)

## API and data

* [Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md): `POST /forgotpassword-v8` sends the link, through php-apis. `GET /dl-ctx/{dynamicLinkUUID}` and `POST /validate-username-v3` check the link. `POST /login-with-otp`, `POST /resend-otp` and `POST /verify-otp` handle codes. `?action=set_user_password_v9` (web) and `?action=set_user_password_v8` (apps) save the new password. The legacy calls are `POST /forgotpassword-v7` and `POST /resetpassword-staffusername-v7`.
* Tables: [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md) (reset links: type, creation time, uses), [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) (temporary-password flags), [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) (password hashes), [`api_token_auth`](https://docs.snapfix.com/engineering-reference/db/tables/api_token_auth.md) (codes) and [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) (the log that holds new passwords).

## Depends on

* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): where the flow starts and ends, and the code rules.
* [Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md): how the reset link opens.
* [App launch](https://docs.snapfix.com/product/features/account/app-launch.md): where the temporary-password screen appears.
* [Profile and settings](https://docs.snapfix.com/product/features/account/profile.md): changing a password, and the legacy reset offered there.
* [Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md): invited users set their first password on the same kind of page.
* [Username logins](https://docs.snapfix.com/product/features/console/username-logins.md): staff usernames.
* [Help Hub](https://docs.snapfix.com/product/features/help/help-hub.md): the "Having trouble loggin in?" links.

## Edge cases

* **Unverified contact:** the web shows "Email not verified." before anything is typed. iOS shows "Email not verified." for phone numbers too.
* **Expired or used link:** the account access page shows "reference expired" or "invalid reference", then sends the person to sign-in ([Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md#states)).
* **Page without link data:** opening the web password page directly still shows the form; saving shows "Something went wrong" and sends nothing.
* **Offline:** iOS and Android check the connection before they send the request and show their alerts. The web shows the shared error alert ([Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md#states)).
* **Time zones:** None.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/account/password-reset.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
