> 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/sign-in.md).

# Sign-in

{% 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/sign-in.md).
{% endhint %}

People sign in to the web app and the mobile apps with an **email address** or a **phone number** and a **password**, or in the apps with a **one-time code** sent by email or SMS. The web app and Android also offer Google, Apple and Microsoft sign-in; the iOS app hides those buttons. A sign-in starts a **session**. The app renews the session in the background with a refresh token. When renewal fails, the app asks the person for a password or a code, or signs them out. There is no sign-up: new people arrive through an invitation, a QR code or a setup form ([Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md)). Links from emails and text messages ([Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md)) and password resets ([Password reset](https://docs.snapfix.com/product/features/account/password-reset.md)) end in the same signed-in state.

## Rules

### What a person signs in with

* Email or phone with a password works on all three platforms. The phone field has a country picker. The login type is remembered on the device, and the first visit starts on email ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#inputs)).
* The Android field also accepts a username ("Please enter email or username"). For staff who have no email or phone, see [Username logins](https://docs.snapfix.com/product/features/console/username-logins.md).
* The web checks only that the email is not empty, that the phone number is valid for the picked country, and that the password is not empty. iOS does not check the email at all, and needs six characters of password before it sends it. Android checks only that the fields are not empty ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#inputs)).
* The web signs in with one call and opens Fix. The apps check the contact first and then the password ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#actions)). On iOS, an access token in the contact check's reply means the account needs no password, and sign-in goes on without one.
* A wrong password gets the server's "invalid credentials" on the web, an inline panel with a reset link or the alert "The username or password is incorrect." on iOS, and "Password Incorrect" on Android ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#actions)).
* If two accounts share a phone number, iOS and Android ask the person to enter the number again ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#dialogs-and-sheets)). authpy matches a phone number by its last digits (`fMobile LIKE '%digits'`), so one national number can match accounts in several countries.
* Sign-in is refused, with the API's message, for a blocked IP address, country, phone, email or user ([Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md), php-apis @ aee9175122, `htmlphp/api/snapfix/class/ip.functions.v3.php`).
* After a password sign-in, iOS and Android keep the password on the phone, unencrypted.
* An admin can block a device from the site's user list ([Site users](https://docs.snapfix.com/product/features/console/site-users.md)). The tokens from that device are then blocked, and the next renewal fails with "invalid access" (authpy @ 5d5758661c, `model/feature_token_ops.py:298-304`).
* Every sign-in screen ends with "Having trouble loggin in?" and a link to the Help Hub.

### One-time code

* iOS offers "Send me a one-time password code" on the sign-in screen and opens [Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md). Android sends the code from [Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md) and checks it on the same step as [Forgot password code](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password-code.md).
* The web sign-in page has no code option: the code step appears only in the mini sign-in dialog ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#platform-differences)) \[[ASK-65](https://github.com/snapfix/docs/blob/main/ASK.md#ask-65-is-sign-in-with-a-one-time-code-meant-to-be-gone-from-the-sign-in-screens)].
* A code has six digits and is sent to the account's email address or phone. It is valid for five minutes and works once (`model/feature_user_auth.py:466`, `:488`); after that the server answers "code expired" ([Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md#inputs)).
* "Resend code" waits for a timer before it can be used again. The web confirms a resend with "An message has been sent" ([Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md#actions)).
* iOS enables "Log In" only for six digits and shows "This code is not correct, please try again." for a wrong code. The web enables its button for any code that is not empty. iOS fills the code in from the SMS ([Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md#platform-differences)).
* The auth service checks each one-time code request against an IP block before it answers (`app.py:735-739`). The limits were not checked for this doc.

### Google, Apple and Microsoft

* The web and Android sign in through the provider's window and then open Fix (web) or the data download (Android) ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#actions)).
* On the web, Microsoft shows "An error occurred while processing your login request" when it fails, unless the person cancels ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#dialogs-and-sheets)).
* iOS hides all three buttons, though the code is still there.
* The help pages say provider sign-in works "if it has been configured within your organisation", but the apps show the buttons to everyone. authpy's sign-on rules only recommend a provider and groups for an email domain.

### Accounts that need a step first

* A temporary password sends the person to [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md) on iOS and Android before the app opens. On the web, an API call that answers 428 opens a create-password dialog (`auth.interceptor.ts`, `global.enum.ts`).
* The server answers 428 when an account has a temporary password, but only to app builds that its version check reads as 6.10.32 or later. Google, Apple and Microsoft sign-ins are not checked (php-apis @ aee9175122, `htmlphp/api/snapfix/class/ip.functions.v3.php:1001-1015`). The version check fails for builds from 6.11.0.
* The server answers 409 to the same builds when the account must be verified and the email or phone used to sign in is not verified. Code calls and the password update are not checked (`ip.functions.v3.php:1017-1045`). The web then shows "Site verification required" with "Go to Profile", and the apps send the person to their profile to verify ([Profile and settings](https://docs.snapfix.com/product/features/account/profile.md)).

### After signing in

* On success the apps save the signed-in user on the phone. The web keeps its tokens and user in the browser's local storage ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#actions)).
* The web looks up the device's approximate location at a third-party site after each sign-in, and sends the result to the server's log.
* The apps then run the data download, as described in [App launch](https://docs.snapfix.com/product/features/account/app-launch.md#data-download).
* A short pre-registration survey can open on Android after the sign-in when the server has one ready (`LoginActivity.kt:314-316`). The iOS code asks for it only from a sign-in screen that nothing opens, so iOS never shows it ([Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md)).
* Each password sign-in counts up the user's login counter and last-login time; Google, Apple and Microsoft sign-ins have their own counters ([`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md)).

### Sessions

* Signing in returns an access token and a refresh token. Both carry the user's verification and temporary-password flags ([Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md)).
* Token lifetimes are set on the server. The code defaults are ten minutes for an access token and one hour for a refresh token. The production values are not in these docs \[[ASK-32](https://github.com/snapfix/docs/blob/main/ASK.md#ask-32-how-long-do-sessions-last-in-production)] (`model/feature_token_ops.py:330`, `:415`).
* The renewal route also accepts expired tokens.
* The web renews an expired token before a request is sent. If a request is refused with 401, it renews once more and retries (`auth.interceptor.ts`).
* When renewal fails on the web, a person who signed in with a password or a code gets the mini sign-in dialog, which cannot be closed: the code step first, with the contact filled in and locked, then "Use password" or "Log out". Anyone else is signed out ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#actions)).
* When renewal fails on Android, a sheet opens that cannot be dismissed. For Google, Apple or Microsoft sign-ins, Android runs the provider sign-in again. For other sign-ins, the sheet offers a code, the password, or logging out (`LoginDialogUtils.java:71-100`). On iOS, a screen offers a code (`ConfirmCodeVC.swift`), and from there the password (`EnterPasswordVC.swift`).

## Flow

```mermaid
flowchart TD
  start["Sign-in screen"] --> how{"How does the person sign in?"}
  how -- "password" --> pw["Enter email or phone, and password"]
  how -- "Google, Apple or Microsoft (web, Android)" --> prov["Provider sign-in window"]
  how -- "one-time code (apps)" --> code["Code sent by email or SMS"]
  pw --> check{"Account and password accepted?"}
  check -- no --> wrong["Message under the field or in an alert"]
  check -- yes --> shared{"Phone number shared by two accounts?"}
  shared -- yes --> again["Enter the phone number again"]
  shared -- no --> temp{"Temporary password?"}
  again --> temp
  prov --> temp
  code --> verify["Check the code"]
  verify -- no --> wrong
  verify -- yes --> temp
  temp -- yes --> setpw["Set password"]
  temp -- no --> session["Session saved"]
  setpw --> session
  session --> next["Fix on the web; the data download, then Home, in the apps"]
```

## Platforms

| Capability                                | Web                                                 | iOS                                                                                                       | Android                                                                                                   |
| ----------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Email or phone with a password            | yes                                                 | yes                                                                                                       | yes, also a username                                                                                      |
| Contact check before sending              | email not empty, phone valid                        | phone valid only                                                                                          | not empty only                                                                                            |
| Google, Apple or Microsoft                | yes                                                 | no                                                                                                        | yes                                                                                                       |
| One-time code from the sign-in screen     | no, only in the mini sign-in dialog                 | yes, [Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md)               | from [Forgot password](https://docs.snapfix.com/how-the-apps-work/screens/account/forgot-password.md)     |
| Shared phone number asks for confirmation | no                                                  | yes                                                                                                       | yes                                                                                                       |
| 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) before the app | [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md) before the app |
| Renewal fails                             | mini sign-in dialog, or sign-out                    | screen: code, or password, or log out                                                                     | sheet that cannot be dismissed: code or password; provider sign-ins sign in again                         |
| Offline                                   | needs a connection                                  | "No internet connection detected. Internet access is required to login."                                  | a connection message                                                                                      |

## Screens

* [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md)
* [Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md)
* [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)
* [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md)
* [Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md), after sign-in

## API and data

* [Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md): the web signs in with `POST /login`. The apps check the contact with `POST /validate-username-v2` and then the password with `?action=check_password_v7`. One-time codes use `POST /login-with-otp`, `POST /verify-otp` and `POST /resend-otp`. Provider sign-in uses `POST /sso-google`, `POST /sso-apple` and `POST /sso-azure`. Renewal uses `POST /refresh` and `POST /refresh-v2`.
* Tables: [`api_token_auth`](https://docs.snapfix.com/engineering-reference/db/tables/api_token_auth.md) (one-time codes), [`token_jwt`](https://docs.snapfix.com/engineering-reference/db/tables/token_jwt.md) (issued tokens and their blocks), and [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) (temporary-password and verification flags, login counters).

## Depends on

* [Password reset](https://docs.snapfix.com/product/features/account/password-reset.md): the forgot-password path and temporary passwords.
* [Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md): sign-in through a link. The apps also open sign-in from `/onboarding` and `/opnLogin` links.
* [Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md): how anyone gets an account.
* [Profile and settings](https://docs.snapfix.com/product/features/account/profile.md): verification, and the password rules for changes.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): device blocks.
* [Username logins](https://docs.snapfix.com/product/features/console/username-logins.md): sign-in for staff without an email or phone.
* [App launch](https://docs.snapfix.com/product/features/account/app-launch.md): what happens after sign-in and at each start.
* [Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md): accounts with no site.
* [Help Hub](https://docs.snapfix.com/product/features/help/help-hub.md): the "Having trouble loggin in?" link.

## Edge cases

* **Wrong password or unknown contact:** the web shows the server's message in the shared alert. iOS and Android show their messages under the field or in an alert ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#actions)).
* **Invitation address on the web:** a `?token=` address shows only a spinner, so the form never appears \[[ASK-28](https://github.com/snapfix/docs/blob/main/ASK.md#ask-28-is-the-authsign-intoken-link-still-sent)].
* **Shared computer:** the web keeps only the chosen login type (email or phone) in the browser. The address typed during a password reset is read once to fill the sign-in page and then cleared.
* **Offline:** the apps show their connection message and send nothing. The web shows the shared error alert ([Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md#states)).
* **Expired code:** the code is refused after five minutes, and the person asks for a new one ([Login code](https://docs.snapfix.com/how-the-apps-work/screens/account/login-code.md#actions)).
* **Deleted profile:** a deleted profile cannot sign in again ([Snapfix profile deleted](https://docs.snapfix.com/how-the-apps-work/screens/account/profile-deleted.md), [Profile and settings](https://docs.snapfix.com/product/features/account/profile.md)).
* **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/sign-in.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.
