> 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/engineering-reference/api/auth.md).

# Auth API

{% 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/spec/api/auth.md).
{% endhint %}

Signing in, tokens, single sign-on, registration, passwords and verification codes.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/v1/app`); `php-apis` at `https://z1.snapfix.com/api/snapfix/index.php`; `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `apipy` at `https://z2.snapfix.com`; `authpy` at `https://z3.snapfix.com` ([Services and hosts](https://docs.snapfix.com/engineering-reference/api.md#services-and-hosts)).
* **Auth:** api\_php\_live\_v2: user token (authpy JWT in `Authorization: Bearer`, [User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens)); the temporary-password gate skips its three routes here ([What a user token does not prove](https://docs.snapfix.com/engineering-reference/api.md#what-a-user-token-does-not-prove)). php-apis: user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]); actions use the `user_uuid` in the request, not the token's user; some actions take HTTP Basic with `AUTH_USERNAME` instead \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]. apipy: `/status` takes an optional user token. authpy: the shared app Basic login built into the apps ([Basic logins](https://docs.snapfix.com/engineering-reference/api.md#basic-logins)). authpy compares it with two server settings and refuses every call when they are missing, because the settings helper raises instead of returning its fallback (authpy @ 5d5758661c, `auth.py:22-30`, `model/utils.py:284-288`). Most authpy routes run the [authpy checks](#authpy-checks) first. Three routes take an encrypted payload and a `snapfix-key` device key ([Encrypted payloads](#encrypted-payloads)). `/dl-ctx` takes the Basic login or a user token, expired ones included; `/refresh` takes a refresh token; `/refresh-v2` also accepts expired tokens of either type; `/status` takes an optional user token. The SSO routes take only the Basic login.
* **Used by:** web\_app\_v2 (sign-in, one-time codes, SSO, password reset, invitation and link pages, token refresh, profile verification and password), web\_payments (the payment page's sign-in and sign-up), webadmin\_angular (sign-in and token refresh), iOS, Android, authpy (relays to php-apis), php-apis; 43 of the 86 endpoints have no known caller.
* **Answers:** each service's envelope is in [Responses](https://docs.snapfix.com/engineering-reference/api.md#responses). authpy answers most errors with HTTP `200` and `result` `false`, and its success message is the lowercase `success` (authpy @ 5d5758661c, `config/constant.py:134-144`).

| Method | Path                                                                                   | Service            | Purpose                                                                                                                                                                                                                        |
| ------ | -------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| POST   | [`/v1/app/user/generate-code`](#post-v1appusergenerate-code)                           | api\_php\_live\_v2 | Send a verification code                                                                                                                                                                                                       |
| PUT    | `/v1/app/user/update-credentials`                                                      | api\_php\_live\_v2 | Change the user's sign-in details (`updateCredentials`) (no caller)                                                                                                                                                            |
| PUT    | [`/v1/app/user/update-password`](#put-v1appuserupdate-password)                        | api\_php\_live\_v2 | Change the user's password                                                                                                                                                                                                     |
| POST   | [`/v1/app/user/verify-code`](#post-v1appuserverify-code)                               | api\_php\_live\_v2 | Check a verification code                                                                                                                                                                                                      |
| ANY    | `?action=api_token_auth`                                                               | php-apis           | Get a one-minute token for the `Snapfix` header, which the actions outside the no-token list need while `SNAPFIX_AUTH_ENABLED` is on (`getAPIAuthToken`) (no caller)                                                           |
| ANY    | `?action=check_password`                                                               | php-apis           | Check any account's password; a match returns that account's data (no caller)                                                                                                                                                  |
| ANY    | `?action=check_password_v650`                                                          | php-apis           | Check a password (v650) (no caller)                                                                                                                                                                                            |
| ANY    | `?action=create_serveronly_forgotpassword`                                             | php-apis           | Reset a user's password and return the new one in the answer (`createForgotPassword`) (no caller)                                                                                                                              |
| ANY    | `?action=edit_user_email_v7`                                                           | php-apis           | Change the user's email (v7) (no caller)                                                                                                                                                                                       |
| ANY    | `?action=edit_user_mobile_v7`                                                          | php-apis           | Change the user's phone number (v7) (no caller)                                                                                                                                                                                |
| ANY    | `?action=edit_user_password`                                                           | php-apis           | Change the user's password (no caller)                                                                                                                                                                                         |
| ANY    | `?action=edit_user_password_v650`                                                      | php-apis           | Change the user's password (v650) (no caller)                                                                                                                                                                                  |
| POST   | [`?action=edit_user_password_v7`](#post-actionedit_user_password_v7)                   | php-apis           | Change the user's password, given the old one (v7)                                                                                                                                                                             |
| ANY    | `?action=forgotpassword_v650`                                                          | php-apis           | Reset the password and send the new one (v650) (no caller)                                                                                                                                                                     |
| POST   | [`?action=forgotpassword_v7`](#post-actionforgotpassword_v7)                           | php-apis           | Reset the password and send the new one by email or SMS (v7), for authpy                                                                                                                                                       |
| POST   | [`?action=forgotpassword_v8`](#post-actionforgotpassword_v8)                           | php-apis           | Send a password reset link by email or SMS (v8), for authpy                                                                                                                                                                    |
| ANY    | `?action=generate_code`                                                                | php-apis           | Send a verification code (`initVerification`) (no caller)                                                                                                                                                                      |
| POST   | [`?action=generate_code_v7`](#post-actiongenerate_code_v7)                             | php-apis           | Send a code to verify the account's email or phone (v7)                                                                                                                                                                        |
| POST   | [`?action=generate_code_v8`](#post-actiongenerate_code_v8)                             | php-apis           | Send a code to verify the account's email or phone (v8), also to an address the account doesn't have yet                                                                                                                       |
| ANY    | `?action=generate_password_hash`                                                       | php-apis           | Disabled: always answers with a fixed error (no caller)                                                                                                                                                                        |
| ANY    | `?action=read_blocked_tokens`                                                          | php-apis           | Read blocked tokens (no caller)                                                                                                                                                                                                |
| ANY    | `?action=read_mail_existence`                                                          | php-apis           | Check whether an email address exists (no caller)                                                                                                                                                                              |
| POST   | [`?action=register_new_user_sso`](#post-actionregister_new_user_sso)                   | php-apis           | Register a user who signed in with SSO, for authpy                                                                                                                                                                             |
| POST   | [`?action=register_new_user_v10`](#post-actionregister_new_user_v10)                   | php-apis           | Register a user from a verified sign-up link (v10), for authpy                                                                                                                                                                 |
| ANY    | `?action=register_new_user_v650`                                                       | php-apis           | Register a user (v650); only an iOS sign-up pager that nothing opens calls it \[[ASK-10](https://github.com/snapfix/docs/blob/main/ASK.md#ask-10-which-differences-between-the-ios-and-android-apps-are-intended)] (no caller) |
| ANY    | `?action=register_new_user_v7`                                                         | php-apis           | Register a user (v7); authpy's proxy returns before it calls this (no caller)                                                                                                                                                  |
| ANY    | `?action=register_new_user_v8`                                                         | php-apis           | Register a user (v8); authpy's proxy returns before it calls this (no caller)                                                                                                                                                  |
| ANY    | `?action=register_new_user_v9`                                                         | php-apis           | Register a user (v9); authpy's proxy returns before it calls this (no caller)                                                                                                                                                  |
| ANY    | `?action=register_parent_business_user`                                                | php-apis           | Register a user with a site and group (`registerParentBusinessUser`) (no caller)                                                                                                                                               |
| POST   | [`?action=resetpassword_staffusername_v7`](#post-actionresetpassword_staffusername_v7) | php-apis           | Ask the site admin to reset a staff username's password, for authpy                                                                                                                                                            |
| POST   | [`?action=save_pri_user_auth_v7`](#post-actionsave_pri_user_auth_v7)                   | php-apis           | Change the user's sign-in email and phone, given the password (v7)                                                                                                                                                             |
| POST   | [`?action=set_user_password_v8`](#post-actionset_user_password_v8)                     | php-apis           | Set the user's password with a fresh token (v8)                                                                                                                                                                                |
| POST   | [`?action=set_user_password_v9`](#post-actionset_user_password_v9)                     | php-apis           | Set the user's password (v9)                                                                                                                                                                                                   |
| ANY    | `?action=validate_mobile_number`                                                       | php-apis           | Check a phone number (no caller)                                                                                                                                                                                               |
| POST   | [`?action=validate_usernames`](#post-actionvalidate_usernames)                         | php-apis           | Find which emails and phone numbers belong to Snapfix accounts                                                                                                                                                                 |
| ANY    | `?action=verify_code`                                                                  | php-apis           | Check a verification code (no caller)                                                                                                                                                                                          |
| POST   | [`?action=verify_code_v7`](#post-actionverify_code_v7)                                 | php-apis           | Check a verification code and mark the email or phone verified (v7)                                                                                                                                                            |
| POST   | [`?action=verify_code_v8`](#post-actionverify_code_v8)                                 | php-apis           | Check a verification code and set the verified email or phone on the account (v8)                                                                                                                                              |
| ANY    | `?action=webcust_login`                                                                | php-apis           | Sign in (`webCustLogin`) (no caller)                                                                                                                                                                                           |
| ANY    | `?action=webcust_change_password`                                                      | php-apis web       | Change the user's password (`updateUserPassword650`) (no caller)                                                                                                                                                               |
| ANY    | `?action=webcust_forgotpassword`                                                       | php-apis web       | Start a password reset (`forgotPassword650`) (no caller)                                                                                                                                                                       |
| ANY    | `?action=webcust_generate_code`                                                        | php-apis web       | Send a verification code (`initVerification`) (no caller)                                                                                                                                                                      |
| ANY    | `?action=webcust_generate_code_v8`                                                     | php-apis web       | Send a verification code (`initVerificationV8`) (no caller)                                                                                                                                                                    |
| ANY    | `?action=webcust_login`                                                                | php-apis web       | Sign in (`checkPassword650`) (no caller)                                                                                                                                                                                       |
| ANY    | `?action=webcust_register_new_user`                                                    | php-apis web       | Register a user (`registerNewUser650`) (no caller)                                                                                                                                                                             |
| ANY    | `?action=webcust_verify_code`                                                          | php-apis web       | Check a verification code (`verifyCode`) (no caller)                                                                                                                                                                           |
| ANY    | `?action=webcust_verify_code_v8`                                                       | php-apis web       | Check a verification code (`verifyCodeV8`) (no caller)                                                                                                                                                                         |
| GET    | `/status`                                                                              | apipy              | Report whether the caller is signed in (`loginStatus`) (no caller)                                                                                                                                                             |
| POST   | `/cipher-text`                                                                         | authpy             | Encrypt any text with the server's key (no caller)                                                                                                                                                                             |
| POST   | [`/device-data`](#post-device-data)                                                    | authpy             | Register the device's keys and get its payload key                                                                                                                                                                             |
| GET    | [`/dl-ctx/{dynamicLinkUUID}`](#get-dl-ctxdynamiclinkuuid)                              | authpy             | Get a dynamic link's context; accepts expired tokens                                                                                                                                                                           |
| POST   | [`/forgotpassword-v7`](#post-forgotpassword-v7)                                        | authpy             | Start a password reset (v7), through php-apis                                                                                                                                                                                  |
| POST   | [`/forgotpassword-v8`](#post-forgotpassword-v8)                                        | authpy             | Start a password reset (v8), through php-apis                                                                                                                                                                                  |
| POST   | `/generate-code-mobile-3yj4e-v9`                                                       | authpy             | Generate a registration code for mobile sign-up (v9) (no caller)                                                                                                                                                               |
| POST   | `/generate-code-mobile-bd7su-v10`                                                      | authpy             | Generate a registration code for mobile sign-up (v10); only unreachable iOS sign-up screens call it (no caller)                                                                                                                |
| POST   | `/generate-code-mobile-hryt54-v8`                                                      | authpy             | Disabled: logs the request and returns before sending a code (no caller)                                                                                                                                                       |
| POST   | `/generate-code-v8`                                                                    | authpy             | Disabled: logs the request and returns before sending a code (no caller)                                                                                                                                                       |
| POST   | [`/generate-code-web-6srw3-v8`](#post-generate-code-web-6srw3-v8)                      | authpy             | Disabled: logs the request and returns before sending a code                                                                                                                                                                   |
| POST   | [`/generate-verification-f3d8x-v11`](#post-generate-verification-f3d8x-v11)            | authpy             | Send a profile verification link for QR onboarding                                                                                                                                                                             |
| POST   | [`/invitee`](#post-invitee)                                                            | authpy             | Get an invitee's email, phone number or staff username                                                                                                                                                                         |
| POST   | [`/login`](#post-login)                                                                | authpy             | Sign in; returns an access token and a refresh token                                                                                                                                                                           |
| POST   | [`/login-with-otp`](#post-login-with-otp)                                              | authpy             | Start a sign-in with a one-time code                                                                                                                                                                                           |
| GET    | [`/mobile-gsm-status`](#get-mobile-gsm-status)                                         | authpy             | Report whether sign-up by phone is switched on, for the apps (`checkGSMStatusForMobileRegistration`)                                                                                                                           |
| POST   | `/plain-text`                                                                          | authpy             | Decrypt any text with the server's key (no caller)                                                                                                                                                                             |
| POST   | [`/refresh`](#post-refresh)                                                            | authpy             | Get a new access token with a refresh token                                                                                                                                                                                    |
| POST   | [`/refresh-v2`](#post-refresh-v2)                                                      | authpy             | Renew tokens; also accepts expired tokens                                                                                                                                                                                      |
| POST   | [`/reg-f3d8x-v11/{dynamiclinkUUID}`](#post-reg-f3d8x-v11dynamiclinkuuid)               | authpy             | Register a temporary user who joins through a QR code (`tempRegisterQRUser`)                                                                                                                                                   |
| POST   | `/register-new-user-v7`                                                                | authpy             | Disabled: logs the request and returns before registering anyone (no caller)                                                                                                                                                   |
| POST   | [`/register-new-user-v8`](#post-register-new-user-v8)                                  | authpy             | Disabled: logs the request and returns before registering anyone                                                                                                                                                               |
| POST   | `/register-new-user-v9`                                                                | authpy             | Disabled: logs the request and returns before registering anyone; only unreachable sign-up screens call it (no caller)                                                                                                         |
| POST   | `/resend-code-mobile-6sdw3-v8`                                                         | authpy             | Resend a registration code for mobile sign-up (v8) (no caller)                                                                                                                                                                 |
| POST   | [`/resend-code-mobile-91r7o-v10`](#post-resend-code-mobile-91r7o-v10)                  | authpy             | Resend a registration code for mobile sign-up (v10)                                                                                                                                                                            |
| POST   | `/resend-code-mobile-ch2h8-v9`                                                         | authpy             | Disabled: logs the request and returns before sending a code (no caller)                                                                                                                                                       |
| POST   | `/resend-code-v8`                                                                      | authpy             | Resend a registration code (v8) (no caller)                                                                                                                                                                                    |
| POST   | [`/resend-code-web-kj6q2-v8`](#post-resend-code-web-kj6q2-v8)                          | authpy             | Resend a registration code for web sign-up (v8)                                                                                                                                                                                |
| POST   | [`/resend-otp`](#post-resend-otp)                                                      | authpy             | Resend a one-time code                                                                                                                                                                                                         |
| POST   | [`/resetpassword-staffusername-v7`](#post-resetpassword-staffusername-v7)              | authpy             | Reset a staff username's password (v7)                                                                                                                                                                                         |
| POST   | [`/sso-apple`](#post-sso-apple)                                                        | authpy             | Sign in with Apple                                                                                                                                                                                                             |
| POST   | [`/sso-azure`](#post-sso-azure)                                                        | authpy             | Sign in with Microsoft (Azure)                                                                                                                                                                                                 |
| POST   | [`/sso-google`](#post-sso-google)                                                      | authpy             | Sign in with Google                                                                                                                                                                                                            |
| GET    | `/status`                                                                              | authpy             | Report whether the caller is signed in (`loginStatus`) (no caller)                                                                                                                                                             |
| POST   | [`/validate-username`](#post-validate-username)                                        | authpy             | Check a username                                                                                                                                                                                                               |
| POST   | [`/validate-username-v2`](#post-validate-username-v2)                                  | authpy             | Check a username (v2); may sign in a user with a temporary password                                                                                                                                                            |
| POST   | [`/validate-username-v3`](#post-validate-username-v3)                                  | authpy             | Check a username with a link ID (v3); may sign the user in                                                                                                                                                                     |
| POST   | [`/verify-otp`](#post-verify-otp)                                                      | authpy             | Check a one-time code and sign in                                                                                                                                                                                              |
| GET    | [`/web-gsm-status`](#get-web-gsm-status)                                               | authpy             | Report whether sign-up by phone is switched on, for the web (`checkGSMStatusForWebRegistration`)                                                                                                                               |

Notes on the table:

* A row gets a section only when code that runs calls it. Registry entries (iOS `APIManagers/ApiEndpointManager.swift`, Android `utils/APIEndPointUtils.java`), constants and screens that nothing opens do not count.
* The legacy iOS sign-up screens `CreateProfileVC`, `SetPasswordVC` and `VerifyAccountVC` are unreachable, and so are both copies of `SmsEmailMainLoginVC` (its storyboard is never loaded and its code start is commented out: ios @ aa31967ac8, `Appdelegate/AppDelegate.swift:253`). Their calls to `/generate-code-mobile-bd7su-v10`, `/register-new-user-v9`, `/resend-code-mobile-91r7o-v10`, `/invitee`, `/mobile-gsm-status` and `/validate-username-v2` do not count.
* web\_app\_v2 has a sign-up page that calls `/generate-code-web-6srw3-v8`, `/resend-code-web-kj6q2-v8`, `/register-new-user-v9` and `/web-gsm-status`, but no route opens it: the auth routes are sign-in, forgot password, set password, the help FAQ and "Get in touch" (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/auth.routes.ts:10-15`) \[[ASK-10](https://github.com/snapfix/docs/blob/main/ASK.md#ask-10-which-differences-between-the-ios-and-android-apps-are-intended)]. The list in `src/app/services/http/http.service.ts:159-178` only picks the requests that get the Basic header; it is not a call.
* Android's call to `/register-new-user-v8` is inside a comment block (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/RegistrationNewActivity.java:619-686`).

## authpy checks

Most authpy routes in this group run two checks. The route section says when one is missing or the order differs.

1. **The abuse check** (`isIPBlocked`, version 3) logs the call and applies the blacklists and limits ([Blocking and rate limits](https://docs.snapfix.com/engineering-reference/api.md#blocking-and-rate-limits)). A blocked caller gets the [blocked answer](#blocked-answer). It runs before the Basic login on most routes, so a call with a wrong login is still logged and counted.
2. **The Basic login.** A wrong or missing one answers `200` with `result` `false` and "invalid authentication".

The limits that apply to this group count rows in `tPri_Log_API_IP_RateLimit` from the last hour (authpy @ 5d5758661c, `model/t_log_ip_blocked_v3.py:222-299`, `:498-578`, `:1557-1559`):

| Calls                                                                                                                          | Limit                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `/login`                                                                                                                       | 20 per username; two staff addresses written in the code are exempt                   |
| `/login-with-otp` per phone number                                                                                             | Never applies: its condition asks for two event names at once (`:244`)                |
| `/verify-otp`                                                                                                                  | 3 per `reference_id`                                                                  |
| `/forgotpassword-v7`, `-v8`                                                                                                    | 20 per `username_estimate`                                                            |
| The resend routes (`/resend-otp`, `/resend-code-web-kj6q2-v8`, `/resend-code-mobile-91r7o-v10` and the uncalled resend routes) | 2 per `reference_id`                                                                  |
| The code-sending routes (sign-in, sign-up, resend, password reset)                                                             | 10 per route from one IP location (latitude and longitude)                            |
| `/resend-otp`, `/forgotpassword-v7`, `-v8` and two uncalled code routes                                                        | 50 per route from one IP in 10 minutes; the IP is then added to `blacklist_ipaddress` |

The per-IP limits trust the first `X-Forwarded-For` address.

**What the check logs:** each request body goes to the API log as `api_req_json`, and each answer up to about 800 KB is added to it (`:1260`, `:1618-1639`). It masks `password`, `password_new` and `password_old`, except on `/reg-f3d8x-v11`, whose form, password included, is logged as sent (`:627`).

**Errors every authpy route can give:** a missing form field or unreadable JSON answers `400` "bad request" (authpy @ 5d5758661c, `app.py:115-117`). Other uncaught errors give a `500` server error; Flask's `DEBUG` is on in the source.

### Blocked answer

`returnIPBlockedResponse` (authpy @ 5d5758661c, `app.py:345-363`):

* `result` `false`, with the blacklist's public message (often "There is an issue with the service you are seeking for. … provide the reference code '…'.") or "There is an issue with the data you have entered. Please try again and contact <support@snapfix.com> if the issue persists.".
* HTTP `409` when the user must verify an email or a phone number first, otherwise `200`.
* When the check's message is `success`, a fake success instead: `result` `true`, HTTP `200`.

The disabled routes in the table always return this answer after the check, so a caller that is not blocked gets `result` `false` with the generic text.

### Encrypted payloads

`/device-data`, `/generate-verification-f3d8x-v11` and `/resend-code-mobile-91r7o-v10` take a JSON body `{"payload": "<base64>"}` (authpy @ 5d5758661c, `key_func.py:133-205`):

* The `snapfix-key` header holds a value encrypted with the server's RSA public key (PKCS#1 v1.5), base64-encoded.
* For `/device-data` that value is a new AES key, and the payload is encrypted with it.
* For the other two, the value is the device ID. The server looks up the device's AES key in `tPri_Device` and decrypts the payload with it ("invalid access" when the device is unknown). The answer's `data.payload` is encrypted with the same key.
* The payload cipher is AES in ECB mode.

## POST /v1/app/user/generate-code

Sends a code to an email address or a phone number, so the signed-in user can confirm it.

* **Auth:** user token. The temporary-password gate does not apply.
* **Used by:** web (the profile's verification step: web\_app\_v2 @ 0989b8e685, `src/app/components/profile-drawer/profile-one-time-password/profile-one-time-password.component.ts:67`, through `src/app/services/profile/profile-http/profile-http.service.ts:60-67`).

**Request** (JSON; the request class renames the fields for the handler: api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Requests/v1/User/GenerateCodeRequest.php:13-55`)

| Name           | In   | Type    | Required                                            | Rules                                                           |
| -------------- | ---- | ------- | --------------------------------------------------- | --------------------------------------------------------------- |
| `generateType` | body | string  | yes                                                 | `email`, `mobile` or `whatsapp` (`app/Enums/VerifyChannel.php`) |
| `username`     | body | string  | when `generateType` is `email`, or no phone is sent | A valid email that no other live account uses                   |
| `countryCode`  | body | integer | for `mobile` and `whatsapp`, or with `mobile`       |                                                                 |
| `mobile`       | body | integer | for `mobile` and `whatsapp`, or with `countryCode`  | Not used by another live account with the same `countryCode`    |

**Response** `200`

```json
{
  "status": "success",
  "message": "Verification Code Sent successfully!",
  "data": null
}
```

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `422` with the first failed rule.

**Side effects** (`app/Http/Controllers/v1/Versions/v1_0/App/UserController.php:223-280`):

* Makes a code of 6 lowercase letters and digits with `array_rand` (`app/Helpers/common.php:362-372`).
* Adds a [credential\_code](https://docs.snapfix.com/engineering-reference/db/tables/credential_code.md) row for the user, with the code and the email, or the country code and number. For WhatsApp the code is `null`: Twilio Verify makes and checks its own code.
* Queues the email (`VerificationCodeEmail`), the SMS "Your Snapfix verification code is …" or the WhatsApp message.
* Writes a [tPri\_Log](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row with the request fields, which do not include the code.

## PUT /v1/app/user/update-password

Changes the signed-in user's password, or sets one when the user has none.

* **Auth:** user token. The temporary-password gate does not apply.
* **Used by:** web (the profile's password dialog: web\_app\_v2 @ 0989b8e685, `src/app/components/profile-drawer/profile-details/profile-details-password-dialog/profile-details-password-dialog.component.ts:95`, through `src/app/services/profile/profile-http/profile-http.service.ts:78-85`).

**Request** (JSON; `app/Http/Requests/v1/User/UpdatePasswordRequest.php`)

| Name                       | In   | Type   | Required                                                                    | Rules                                                                    |
| -------------------------- | ---- | ------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `newPassword`              | body | string | yes                                                                         | At least 8 characters, with a digit, a lowercase and an uppercase letter |
| `newPassword_confirmation` | body | string | yes                                                                         | The same value                                                           |
| `oldPassword`              | body | string | when the token is not fresh and its `temp_password` claim is `0` or missing | Checked against the stored hash when sent                                |

**Response** `200`: `status` `success`, `message` "Password updated successfully.", `data` `null`.

**Errors:** [common errors](https://docs.snapfix.com/engineering-reference/api/tasks.md#common-errors); `406` "Invalid user" when `oldPassword` does not match; `422` when a rule fails.

**Side effects** (`UserController.php:147-183`):

* Updates `fHash` in [tPri\_UserHashSalt](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) with the user's salt, or adds a row with a new salt. The hash is `ripemd160` of the password's `ripemd160` plus the salt (`app/Helpers/common.php:32`, `:398-408`).
* Sets `temp_password` to `0` on [tPri\_User](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md).

## POST /v1/app/user/verify-code

Checks a code from [generate-code](#post-v1appusergenerate-code) and marks the email or phone number as verified.

* **Auth:** user token. The temporary-password gate does not apply.
* **Used by:** web (the profile's verification dialog: web\_app\_v2 @ 0989b8e685, `src/app/components/profile-drawer/profile-verification-dialog/profile-verification-dialog.component.ts:58`, through `src/app/services/profile/profile-http/profile-http.service.ts:69-76`).

**Request** (JSON; `app/Http/Requests/v1/User/VerifyCodeRequest.php`)

| Name                    | In   | Type    | Required                    | Rules                                                                                                                                             |
| ----------------------- | ---- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verifyType`            | body | string  | yes                         | `email`, `mobile` or `whatsapp`; otherwise "Invalid type to verify"                                                                               |
| `code`                  | body | string  | yes                         | Exactly 6 characters. For `email` and `mobile` it must exist in some `credential_code` row of that channel, otherwise "Invalid verification code" |
| `username`              | body | string  | for `email`                 | Not used by another live account                                                                                                                  |
| `countryCode`, `mobile` | body | integer | for `mobile` and `whatsapp` | Not used by another live account                                                                                                                  |

A missing contact field gives "Invalid parameters".

**Response** `200`: `status` `success`, `message` "Code verified successfully", `data` `null`.

**Errors** (`UserController.php:290-367`): `422` for the rules above; `400` with:

* "Invalid code": the user has no code row, the code is not the user's newest one, or Twilio rejects a WhatsApp code.
* "Code expired": the newest code is 30 days old or more \[[ASK-31](https://github.com/snapfix/docs/blob/main/ASK.md#ask-31-should-profile-verification-codes-last-30-days)].
* "Mobile details do not match" or "Username does not match": the contact is not the one the code was sent to.

**Side effects:**

* Sets `fUsername` and `email_verified` `1`, or `fCountryCode`, `fMobile` and `mobile_verified` `1`, on [tPri\_User](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md).
* Writes a [tPri\_Log](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row with the whole request, the code included.
* The code row is not marked used, so the same code passes again until a newer code is made or it expires.

## POST /device-data

Registers the device's public key, TOTP key and push token, and returns the AES key for its later [encrypted payloads](#encrypted-payloads).

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** iOS (ios @ aa31967ac8, `Managers/Security Helpers/SecurityManager.swift:82`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/AppSecurity.java:173-187`).

**Request** (JSON, authpy @ 5d5758661c, `app.py:1607-1644`; `model/t_device_data.py:31-110`)

| Name          | In     | Type   | Required | Rules                                                                                                                                   |
| ------------- | ------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `snapfix-key` | header | string | yes      | A new AES key, encrypted with the server's RSA key                                                                                      |
| `payload`     | body   | string | yes      | Encrypted JSON with `key20` (device ID), `key21` (the device's public key), `key23` (TOTP key) and `key26` (push token), each non-blank |

**Response** `200`: `data.payload` is `{"key30": "<AES key>"}` encrypted with the device's public key.

**Errors:** "invalid params" without `payload`; "invalid key20" (and so on) for a blank field; "failed to save device".

**Side effects:** adds a `tPri_Device` row, or updates the device's live row when a key or the token changed. Each add or change makes a new AES key.

## GET /dl-ctx/{dynamicLinkUUID}

Opens a dynamic link (a QR invitation, a user invitation, a password reset link or a profile verification link) and returns what the app needs for the next step.

* **Auth:** [authpy checks](#authpy-checks) first. Then either the Basic login, or a user token in `Authorization: Bearer`, which may be expired and is not checked for type. A wrong Basic login is treated as a token and answers `401` "Invalid token".
* **Used by:** web (`/account-access`: web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/account-access/account-access.component.ts:61`); iOS (ios @ aa31967ac8, `Managers/DeepLink/DynamicLinkContextDeeplinkHandler.swift:146`, with the token when signed in: the registry's `dl-ctx-logged-in` is the same URL, `APIManagers/ApiEndpointManager.swift:3242-3247`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/LoginRepository.kt:111-115`, and `:142-146` with the token as `dl-ctx-bearer`, also the same URL, `utils/APIEndPointUtils.java:525`).

**Request**

| Name              | In   | Type   | Required | Rules                                                   |
| ----------------- | ---- | ------ | -------- | ------------------------------------------------------- |
| `dynamicLinkUUID` | path | string | yes      | A live `dynamiclink` row; otherwise "invalid reference" |

**Response** `200`: a [dynamic link context](#dynamic-link-context-object). With the Basic login and the message "Verified successfully" (a verified profile), the answer is php-apis's answer itself instead of the envelope (authpy @ 5d5758661c, `app.py:2404-2463`).

**Errors:** "invalid access" with no `Authorization` header; `401` "Invalid token" when the token does not decode; the messages in the [context object](#dynamic-link-context-object).

**Side effects** (`model/feature_token_ops.py:3546-3615`):

* Adds 1 to the link's `count_opened`.
* A QR invitation opened by a signed-in user adds the user to the invitation's site.
* A reset link sets `temp_password` `1` and `temp_password_required` `0` on the user. It is never marked used, so it works again for its 15 minutes.
* A profile verification link sends the stored sign-up form to php-apis `register_new_user_v10`, marks the QR invitation it came from as used, and sends an acknowledgement. The verification link itself is not marked used.

## POST /forgotpassword-v7

Starts a password reset by relaying the request to php-apis `forgotpassword_v7`.

* **Auth:** the Basic login first, then the [authpy checks](#authpy-checks). A wrong login gives a `500` server error instead of "invalid authentication", because the error branch reads a variable that is not set yet (authpy @ 5d5758661c, `app.py:485-507`).
* **Used by:** iOS (ios @ aa31967ac8, `SnapFix/MySettingsVC.swift:1127`, `SnapFix/New Profile/Profile/ViewModels/ProfileViewModel.swift:167`, `SnapFix/ResetPasswordVC.swift:217`, `SnapFix/UpdatePassword/UpdatePasswordVC.swift:386`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/MyProfileActivity.kt:1368`, `activity/BusinessListingActivity.java:3498`, `activity/ResetPasswordActivity.java:442`).

**Request:** JSON only (`json.loads` of the body); the fields are php-apis's (`forgotpassword_v7`).

**Response:** php-apis's answer, unchanged.

**Errors:** the [blocked answer](#blocked-answer); php-apis's errors. Without an `X-Forwarded-For` header the relay fails with a server error (`model/feature_php_api.py:56-59`).

**Side effects:** php-apis's. The reply says whether an account exists for the name \[[ASK-228](https://github.com/snapfix/docs/blob/main/ASK.md#ask-228-should-sign-in-tell-an-unknown-contact-from-a-wrong-password)].

## POST /forgotpassword-v8

Starts a password reset by relaying the request to php-apis `forgotpassword_v8`, which sends a reset link.

* **Auth:** as [forgotpassword-v7](#post-forgotpassword-v7), with the same `500` on a wrong login (authpy @ 5d5758661c, `app.py:510-528`).
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/forgot-password/forgot-password.component.ts:120`, through `src/app/services/auth/auth-http/auth-http.service.ts:126-133`, which sends `{"username_estimate": "jane@example.com", "origin": "web"}`); iOS (ios @ aa31967ac8, `SnapFix/Forgot Password/OTPService.swift:125`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/LoginRepository.kt:200-201`).

**Request:** JSON only; the fields are php-apis's.

**Response:** php-apis's answer, unchanged.

**Errors:** the [blocked answer](#blocked-answer); php-apis's errors; a server error without `X-Forwarded-For` (`model/feature_php_api.py:67-70`).

## POST /generate-code-web-6srw3-v8

Meant to send a registration code for web sign-up. It is switched off: after the abuse check it always returns the [blocked answer](#blocked-answer), and no code is sent (authpy @ 5d5758661c, `app.py:935-963`).

* **Auth:** none is checked. The Basic check after the early return never runs.
* **Used by:** web\_payments sign-up (web\_payments @ 7c2c3ddffd, `src/app/pages/auth/pay/components/pay-user-register/pay-user-register.component.ts:153`, through `src/app/services/auth/auth.service.ts:70-76`), which therefore never reaches its code step.

**Request** (form): `username_estimate`, and `recaptcha_token` from the page; neither is read.

**Response** `200`: `result` `false` with the generic text.

**Side effects:** the abuse check logs the call.

## POST /generate-verification-f3d8x-v11

Starts the QR sign-up: checks that the email or number is free, and sends a profile verification link by email or SMS.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login; an [encrypted payload](#encrypted-payloads).
* **Used by:** iOS QR sign-up (ios @ aa31967ac8, `SnapFix/Sign up/Sign up with Qr /SignupPasswordVC.swift:211`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/RegistrationNewActivity.java:415-418`).

**Request:** the decrypted payload (authpy @ 5d5758661c, `app.py:1182-1214`):

| Name                    | In      | Type   | Required | Rules                                                                                    |
| ----------------------- | ------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `username_estimate`     | payload | string | yes      | An email or a phone number with country code; must not belong to an account              |
| `ctx`                   | payload | string | yes      | The QR invitation link's UUID: an unused `qrcode-invitation` link with an invitation row |
| `firstname`, `lastname` | payload | string | no       | Put in the message                                                                       |
| `origin`                | payload | string | no       |                                                                                          |

**Response** `200`: `data.payload` is `{"reference_id": "<uuid>"}`, encrypted: the UUID of the new verification link. The message is "A verification email has been sent to …" or "A verification SMS has been sent to +…", with the full address or number.

**Errors** (`model/feature_user_auth.py:1493-1597`): "Email already exists!", "Mobile Number already exists!", "user account already exists!", "invalid invitation!", "invalid number format or country code".

**Side effects:** adds a `verify_profile` `dynamiclink` row that points to the QR invitation, and sends "Verify Your Snapfix User Profile" with the link.

## POST /invitee

Returns the sign-in contact of the person an invitation is for, so the sign-in page can fill it in.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login. Any caller with an invitation token gets the contact.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/sign-in/sign-in.component.ts:231`, through `src/app/services/auth/auth-http/auth-http.service.ts:161-169`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/LoginUsernameActivity.java:918-921`).

**Request** (JSON, authpy @ 5d5758661c, `app.py:2356-2384`)

| Name    | In   | Type   | Required | Rules                                              |
| ------- | ---- | ------ | -------- | -------------------------------------------------- |
| `token` | body | string | yes      | The UUID of a `tPri_UserParent` row of a live user |

**Response** `200` (`model/feature_token_ops.py:3530-3544`): `data` is one of these, checked in this order:

```json
{ "loginType": "email", "email": "jane@example.com" }
```

`{"loginType": "mobile", "countrycode": 44, "mobile": "7700900123"}`, or `{"loginType": "staff_username", "staff_username": "jane.doe"}`.

**Errors:** "invalid token"; "invalid loginType" when the user has none of the three.

## POST /login

Signs in with a username and a password.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/sign-in/sign-in.component.ts:108`); web\_payments (web\_payments @ 7c2c3ddffd, `src/app/pages/auth/pay/pay.component.ts:105`); webadmin\_angular (webadmin\_angular @ db972390b8, `src/app/pages/login/login.component.ts:46`); iOS and Android through the registry entry `check_password_v7`, which points to `/login` (ios @ aa31967ac8, `SnapFix/AutoLogin/EnterPasswordVC.swift:160`, `SnapFix/SmsEmailLogin/SmsEmailLoginVC/SmsEmailLoginVC.swift:434`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/LoginRepository.kt:53`, `utils/APIEndPointUtils.java:332`).

**Request** (form fields only, authpy @ 5d5758661c, `app.py:390-447`)

| Name       | In   | Type   | Required | Rules                                                                                                                                                                                |
| ---------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `username` | body | string | yes      | An email, a phone number (digits, `+` allowed) or a staff username. A phone number matches any account whose number ends with those digits. `"`, `` ` ``, `;` or `#` make it invalid |
| `password` | body | string | yes      | At least 6 characters, otherwise "The password must be at least six characters long"                                                                                                 |

**Response** `200`: a [sign-in result](#sign-in-result-object), with `temporary` `true` when the password is shorter than 8 characters.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1700000000000,
  "access_token": "example-access-token",
  "refresh_token": "example-refresh-token",
  "user_data": { "uuid": "{uuid}", "fUsername": "jane@example.com", "loginType": "email" },
  "temporary": false
}
```

**Errors** (`model/feature_user_auth.py:81-366`): "invalid credentials" (no account), "user duplicate found" (more than one), "Incorrect password", "The username and password must be a valid string". The answers tell a missing account from a wrong password \[[ASK-228](https://github.com/snapfix/docs/blob/main/ASK.md#ask-228-should-sign-in-tell-an-unknown-contact-from-a-wrong-password)].

**Side effects:**

* Checks the salted `ripemd160` hash in `tPri_UserHashSalt`. When that fails or is missing, it tries an unexpired row in `tPri_UserHashSalt_Temporary`, sets `admin_temp_password` and expires a single-use row.
* Makes fresh tokens, and stores both tokens and the device info through the token store (`featureTokenOps`).
* Updates `snapfix_user_login_count` and `snapfix_user_lastlogin_ts` on [tPri\_User](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md).
* The abuse check's log keeps `user_data` from the answer.

## POST /login-with-otp

Sends a one-time sign-in code to the account's email address or phone number.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/sign-in/sign-in-otp/sign-in-otp.component.ts:83`, `src/app/pages/auth/forgot-password/otp/otp.component.ts:114`, `src/app/pages/auth/forgot-password/forgot-password.component.ts:320`; it sends a `note` header, `login-screen` or `mini-login`); iOS (ios @ aa31967ac8, `SnapFix/Forgot Password/OTPService.swift:70`, `:81`, `SnapFix/SmsEmailLogin/SmsEmailLoginVC/SmsEmailLoginVC.swift:711`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/LoginRepository.kt:252-253`, `fragment/LoginFragment.java:929`, `bottomSheet/LoginBottomSheet.java:473`, `bottomSheet/AutoLoginBottomSheet.kt:327`).

**Request** (form, authpy @ 5d5758661c, `app.py:733-758`)

| Name                | In   | Type   | Required | Rules                                  |
| ------------------- | ---- | ------ | -------- | -------------------------------------- |
| `username_estimate` | body | string | yes      | As `username` in [/login](#post-login) |

The apps also send `countrycode` and `send_via`. authpy reads neither, so iOS's WhatsApp choice is sent by SMS or email \[[ASK-34](https://github.com/snapfix/docs/blob/main/ASK.md#ask-34-is-whatsapp-delivery-of-one-time-codes-meant-to-ship)].

**Response** `200`: `data.reference_id`, and the message "An email has been sent to <jane@example.com>" or "An SMS has been sent to +447700900123", with the account's full address or number.

**Errors** (`model/feature_user_auth.py:383-524`): "user account does not exist!", "user account duplicate found. Please contact our admin!", "Please contact your admin to update your email/mobile." (a staff username with neither), "invalid number format or country code".

**Side effects:**

* A staff username gets the code at the account's email, or else its phone.
* Adds an `api_token_auth` row: single use, valid 300 seconds, with the code, the receiver and the message in `fNote` in plain text. The code is 6 digits from a non-cryptographic generator.
* Sends the email "Your One-Time Code" (SES) or an SMS (SNS).
* Each call sends a new code: nothing limits the sends per account or number beyond the per-location limit.

## GET /mobile-gsm-status

Tells the apps whether sign-up by phone number is switched on.

* **Auth:** [authpy checks](#authpy-checks) (a blocked caller gets the [blocked answer](#blocked-answer)), then the Basic login.
* **Used by:** Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/LoginUsernameActivity.java:483-486`).

**Response** `200`: `data.gsm_registration`, `true` when the setting in `tPub_GlobalValues` is `1` (authpy @ 5d5758661c, `app.py:906-932`; `model/feature_user_auth.py:1730-1746`).

**Errors:** "invalid settings" when the setting is missing.

## POST /refresh

Returns a new access token for a refresh token.

* **Auth:** a refresh token in `Authorization: Bearer`, then the [authpy checks](#authpy-checks).
* **Used by:** webadmin\_angular, when a call answers `401` (webadmin\_angular @ db972390b8, `src/app/services/auth/auth-interceptor/auth.interceptor.ts:59`, through `src/app/services/auth/auth.service.ts:31-33`).

**Response** `200`: `access_token` at the top level, not fresh. No new refresh token (authpy @ 5d5758661c, `app.py:171-205`).

**Errors:** `401` with the message for a token the server rejects; the token library's own answer for a missing, expired or non-refresh token.

## POST /refresh-v2

Renews the tokens. It also takes an expired token.

* **Auth:** a token in `Authorization: Bearer`. An expired token of either type is accepted, which lets an expired access token renew the session.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/services/auth/auth-token/auth-token.service.ts:54`, `src/app/services/profile/profile-helper/profile-helper.service.ts:171`); iOS (ios @ aa31967ac8, `SVProgressHUD/JWTHelper.swift:24-32`, called from `APIManagers/APIManager.swift:1419` and `:1751`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/tasks/RefreshTokensTask.java:105-109`).

**Request:** no body.

**Response** `200`: `access_token`, and `refresh_token` when the renewal makes one (authpy @ 5d5758661c, `app.py:217-328`).

**Errors:**

* `409` "invalid user" when the token has no user.
* `409` "Refresh token expired" without an `Authorization` header.
* `409` with the message for a token that does not decode.
* The [blocked answer](#blocked-answer).

For an expired token the code reads the header twice, and the second read removes only `Bearer` , so a header written `BEARER` does not decode (`app.py:265-266`).

## POST /reg-f3d8x-v11/{dynamiclinkUUID}

Saves the QR sign-up form against the profile verification link. The account is made when the person opens the link ([dl-ctx](#get-dl-ctxdynamiclinkuuid)).

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** iOS QR sign-up (ios @ aa31967ac8, `SnapFix/Sign up/Sign up with Qr /SignupPasswordVC.swift:339`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/RegistrationNewActivity.java:519-544`).

**Request** (plain multipart form, not encrypted; authpy @ 5d5758661c, `app.py:1216-1244`)

| Name              | In   | Type   | Required | Rules                                                                                                                                                                                                                                                                        |
| ----------------- | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dynamiclinkUUID` | path | string | yes      | The `reference_id` from [generate-verification](#post-generate-verification-f3d8x-v11): a `verify_profile` link, otherwise "invalid invitation!"                                                                                                                             |
| `profile_image`   | body | file   | no       | Uploaded to S3 and stored as `fImage`                                                                                                                                                                                                                                        |
| other fields      | body | string |          | The sign-up form as the app sends it. Android sends `name_of_user`, `fFirstName`, `fLastName`, `fOrigin`, `email`, `country_code`, `mobile`, `password_new`, `account_and_product_updates`, `terms_and_conditions_agreed`, `terms_and_conditions_text` and `onboarding_code` |

**Response** `200`: `result` `true`, "User registration is under verification.".

**Errors:** "invalid invitation!". Without an `X-Forwarded-For` header the call fails with a server error, the same way the php-apis proxies do (`model/feature_user_auth.py:1599-1626`).

**Side effects:** stores the whole form, password included, as JSON in the link's `reg_payload`. The abuse check logs the form unmasked.

## POST /register-new-user-v8

Meant to register a user through php-apis. It is switched off: after the Basic login and the abuse check it always returns the [blocked answer](#blocked-answer), and php-apis is never called (authpy @ 5d5758661c, `app.py:1279-1294`).

* **Auth:** the Basic login first, then the abuse check.
* **Used by:** web\_payments sign-up (web\_payments @ 7c2c3ddffd, `src/app/pages/auth/pay/components/pay-user-register/pay-user-register.component.ts:111`, through `src/app/services/auth/auth.service.ts:43-47`), which never gets past its code step.

**Request:** JSON; nothing is read beyond the abuse check.

**Response** `200`: `result` `false` with the generic text, or "invalid authentication".

## POST /resend-code-mobile-91r7o-v10

Resends a registration code under a new reference.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login; an [encrypted payload](#encrypted-payloads).
* **Used by:** Android QR sign-up (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/RegistrationVerificationFragment.java:378-381`). The app sends the QR flow's verification link, which has no code row, so the resend always fails "invalid reference".

**Request:** decrypted payload with `reference_id` (authpy @ 5d5758661c, `app.py:1246-1276`).

**Response** `200`: `data.payload`, the encrypted `{"reference_id": "<new uuid>"}`, and the original message.

**Errors and side effects:** as [resend-code-web-kj6q2-v8](#post-resend-code-web-kj6q2-v8).

## POST /resend-code-web-kj6q2-v8

Resends a registration code under a new reference.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** web\_payments sign-up (web\_payments @ 7c2c3ddffd, `src/app/pages/auth/pay/components/pay-user-register/pay-user-register.component.ts:153`, through `src/app/services/auth/auth.service.ts:70-76`). The page never reaches its code step, because the first code is never sent.

**Request** (form, authpy @ 5d5758661c, `app.py:996-1023`)

| Name           | In   | Type   | Required | Rules                                                      |
| -------------- | ---- | ------ | -------- | ---------------------------------------------------------- |
| `reference_id` | body | string | yes      | A live `api_token_auth` row, otherwise "invalid reference" |

**Response** `200`: `data.reference_id`, a new one, and the original message.

**Errors:** "invalid reference"; "invalid number format or country code".

**Side effects** (`model/feature_user_auth.py:1628-1728`): marks the old row deleted and adds a row with a new UUID, a new 6-digit code and 300 seconds. The old row's expiry is not checked, so an expired sign-up can be resent. The code is in `fNote` in plain text.

## POST /resend-otp

Sends a new sign-in code under the same reference.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** iOS (ios @ aa31967ac8, `SnapFix/AutoLogin/ConfirmCodeVC.swift:394`, `SnapFix/SmsEmailLogin/SMSEmailOTP/SmsEmailOtpVC.swift:414`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/LoginRepository.kt:226-227`, `fragment/LoginOtpFragment.java:507`, `bottomSheet/LoginOtpBottomSheet.java:476`).

**Request** (form, authpy @ 5d5758661c, `app.py:769-794`)

| Name           | In   | Type   | Required | Rules                                                                                  |
| -------------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `reference_id` | body | string | yes      | From [login-with-otp](#post-login-with-otp); a live row, otherwise "invalid reference" |

**Response** `200`: `data.reference_id`, the same one, and the original message with the full contact.

**Errors:** "invalid reference"; "invalid number format or country code".

**Side effects** (`model/feature_user_auth.py:540-646`): renames the old row's UUID and marks it deleted, then adds a row with the same `reference_id`, a new code and a new 300 seconds. The old row's expiry is not checked, so an expired sign-in gets a new window; two resends per reference an hour are allowed ([authpy checks](#authpy-checks)).

## POST /resetpassword-staffusername-v7

Resets a staff username's password by relaying to php-apis `resetpassword_staffusername_v7`.

* **Auth:** the Basic login, then the abuse check, whose result is ignored: a blocked caller still gets through (authpy @ 5d5758661c, `app.py:535-546`).
* **Used by:** iOS (ios @ aa31967ac8, `SnapFix/MySettingsVC.swift:1164`, `SnapFix/New Profile/Profile/ViewModels/ProfileViewModel.swift:204`, `SnapFix/UpdatePassword/UpdatePasswordVC.swift:424`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:3483`, `activity/MyProfileActivity.kt:1351`, `activity/ResetPasswordActivity.java:432`). Both apps' registries have a space at the end of the URL.

**Request:** JSON only; the fields are php-apis's.

**Response:** php-apis's answer, unchanged.

**Errors:** php-apis's; a server error without `X-Forwarded-For` (`model/feature_php_api.py:78-81`).

## POST /sso-apple

Signs in, or signs up, with an Apple ID token.

* **Auth:** the Basic login only. These three SSO routes skip the abuse check.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/single-sign-on/single-sign-on.component.ts:80`); iOS (ios @ aa31967ac8, `SnapFix/SmsEmailLogin/SSOManager/SSOManager+Functions.swift:150`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/SSOManager.java:105-106`).

**Request** (form, authpy @ 5d5758661c, `app.py:1647-1661`; `model/feature_user_auth.py:2032-2451`)

| Name                                     | In   | Type   | Required | Rules                                                                                                                                      |
| ---------------------------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `token`                                  | body | string | yes      | An Apple ID token. Its signature is checked with Apple's keys, and its issuer, audience (either of the two app IDs), expiry and issue time |
| `app_src`                                | body | string | yes      | `web`, `ios` or `android`                                                                                                                  |
| `email`                                  | body | string | no       | Must equal the token's email when sent                                                                                                     |
| `name`, `firstname`, `lastname`, `image` | body | string | no       | Used for a new account; `name` is required then                                                                                            |
| `ctx`                                    | body | string | no       | A dynamic link UUID, passed on to the sign-up                                                                                              |

**Response** `200`: an [SSO result](#sso-result-object).

**Errors:** "invalid token", "invalid app\_src", "invalid name", "Apple login is not possible using this account. …" (the email's domain does not allow Apple sign-in), "Apple login is not possible using this account because there is an existing Snapfix account that uses the same email address and you have not verified the email address. …", "user account duplicate found. Please contact our admin!", "Please contact your site admin to enable your access into the site.", php-apis's sign-up errors.

**Side effects:** see the [SSO result](#sso-result-object).

## POST /sso-azure

Signs in, or signs up, with a Microsoft ID token.

* **Auth:** the Basic login only; no abuse check.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/single-sign-on/single-sign-on.component.ts:104`); iOS (ios @ aa31967ac8, `SnapFix/SmsEmailLogin/SSOManager/SSOManager+Functions.swift:154`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/SSOManager.java:129-130`).

**Request** (form, authpy @ 5d5758661c, `app.py:1686-1702`; `model/feature_user_auth.py:2897-3240`)

| Name                                    | In   | Type   | Required | Rules                                                                                                                                 |
| --------------------------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                                 | body | string | yes      | A Microsoft ID token, checked with Microsoft's keys, for audience, expiry and issue time. Its `preferred_username` must equal `email` |
| `access_token`                          | body | string | yes      | Used for the domain's sign-in rules                                                                                                   |
| `app_src`                               | body | string | yes      |                                                                                                                                       |
| `email`                                 | body | string | yes      |                                                                                                                                       |
| `name`                                  | body | string | yes      |                                                                                                                                       |
| `firstname`, `lastname`, `image`, `ctx` | body | string | no       | As for Apple                                                                                                                          |

**Response** `200`: an [SSO result](#sso-result-object).

**Errors:** "invalid token", "invalid access\_token", "invalid app\_src", "invalid email", "invalid name", the "Azure login is not possible …" messages, "user account duplicate found. Please contact our admin!", "Please contact your site admin to enable your access into the site.".

## POST /sso-google

Signs in, or signs up, with Google.

* **Auth:** the Basic login only; no abuse check.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/single-sign-on/single-sign-on.component.ts:144`, sends `authorization_code` and `app_src` `web`); iOS (ios @ aa31967ac8, `SnapFix/SmsEmailLogin/SSOManager/SSOManager+Functions.swift:152`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/SSOManager.java:78-79`).

**Request** (form, authpy @ 5d5758661c, `app.py:1664-1684`; `model/feature_user_auth.py:2453-2891`)

| Name                                       | In   | Type   | Required             | Rules                                                                                                                                                    |
| ------------------------------------------ | ---- | ------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_src`                                  | body | string | yes                  | `web`, `ios` or `android`; picks the Google client ID. Android's `debug_mode` picks the same one either way                                              |
| `authorization_code`                       | body | string | for `web`            | Exchanged with Google for the tokens; the email and name then come from the verified ID token. The client secret for the exchange is written in the code |
| `token`                                    | body | string | for `ios`, `android` | A Google ID token, checked with Google for the app's client ID                                                                                           |
| `access_token`, `user_id`, `email`, `name` | body | string | for `ios`, `android` | `email` is not compared with the token, so the account is chosen by the email the app sends                                                              |
| `firstname`, `lastname`, `image`, `ctx`    | body | string | no                   | As for Apple                                                                                                                                             |

**Response** `200`: an [SSO result](#sso-result-object).

**Errors:** "invalid app\_src", "invalid authorization\_code", "failed to validate authorization\_code", "invalid token", "invalid access\_token", "invalid user\_id", "invalid email", "invalid name", "failed to verify user token", the "Google login is not possible …" messages, "user account duplicate found. Please contact our admin!", "Please contact your site admin to enable your access into the site.".

## POST /validate-username

Checks whether an email, phone number or staff username has an account, and which sign-in methods its domain allows.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** web\_payments (web\_payments @ 7c2c3ddffd, `src/app/pages/auth/pay/pay.component.ts:83`); iOS (ios @ aa31967ac8, `SnapFix/Forgot Password/ForgotPasswordViewModel.swift:136`, `SnapFix/Forgot Password/OTPService.swift:48`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/SSOFragment.java:160`, `fragment/RegistrationProfileNewFragment.java:580`, `bottomSheet/CreateUserProfileBottomSheet.kt:754`).

**Request** (form, authpy @ 5d5758661c, `app.py:623-654`)

| Name                | In   | Type   | Required | Rules                                  |
| ------------------- | ---- | ------ | -------- | -------------------------------------- |
| `username_estimate` | body | string | yes      | As `username` in [/login](#post-login) |

The apps also send `countrycode`; it is not read.

**Response** `200`: `data` is a [username check](#username-check-object).

**Errors** (`model/feature_user_auth.py:780-1213`): "invalid email or mobile number", " does not exist!", "user account duplicate found. Please contact our admin!". The answers say whether a contact has an account and whether it is verified \[[ASK-228](https://github.com/snapfix/docs/blob/main/ASK.md#ask-228-should-sign-in-tell-an-unknown-contact-from-a-wrong-password)].

## POST /validate-username-v2

The sign-in page's username check. Like [validate-username](#post-validate-username), but a user with a temporary password from a reset link is signed in at once.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/sign-in/sign-in.component.ts:190`, `src/app/pages/auth/forgot-password/forgot-password.component.ts:343`); iOS (ios @ aa31967ac8, `SnapFix/SmsEmailLogin/SmsEmailLoginVC/SmsEmailLoginVC.swift:383`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/LoginUsernameActivity.java:824-827`, `repository/LoginRepository.kt:27`).

**Request** (form, authpy @ 5d5758661c, `app.py:657-688`): `username_estimate`, as in [validate-username](#post-validate-username).

**Response** `200`:

* Usually `data` is a [username check](#username-check-object).
* When the account has `temp_password` `1` and `temp_password_required` `0` (set by a reset link), the answer is "You must set a new password to proceed." with `access_token` and `refresh_token` at the top level and `data.user_data`.

**Errors:** as [validate-username](#post-validate-username).

## POST /validate-username-v3

The `/account-access` page's check: a username plus the dynamic link it came from. It can sign the user in.

* **Auth:** [authpy checks](#authpy-checks), then the Basic login.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/account-access/account-access.component.ts:81`, through `src/app/services/auth/auth-http/auth-http.service.ts:34-43`); iOS (ios @ aa31967ac8, `Managers/DeepLink/DynamicLinkContextDeeplinkHandler.swift:190`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/LoginRepository.kt:174`).

**Request** (form, authpy @ 5d5758661c, `app.py:691-722`)

| Name                | In   | Type   | Required | Rules                                                                                                                 |
| ------------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `username_estimate` | body | string | yes      | As in [validate-username](#post-validate-username)                                                                    |
| `ctx`               | body | string | yes      | A dynamic link UUID. The route treats it as optional, but the check answers "reference not found" without a known one |

**Response** `200`: `access_token`, `refresh_token` and `data.user_data`. The message is "Verified successfully", and the account's `email_verified` and `mobile_verified` are set. For a user invitation link the invited user row is marked onboarded and the link used.

**Errors:** "reference not found", and those of [validate-username](#post-validate-username).

## POST /verify-otp

Checks a one-time sign-in code and signs the user in.

* **Auth:** [authpy checks](#authpy-checks) (3 tries per reference an hour), then the Basic login.
* **Used by:** web (web\_app\_v2 @ 0989b8e685, `src/app/pages/auth/sign-in/sign-in-otp/sign-in-otp.component.ts:121`, `src/app/pages/auth/forgot-password/otp/otp.component.ts:156`); iOS (ios @ aa31967ac8, `SnapFix/Forgot Password/OTPService.swift:96`, `SnapFix/SmsEmailLogin/SMSEmailOTP/SmsEmailOtpVC.swift:205`); Android (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/LoginRepository.kt:282`, `bottomSheet/LoginOtpBottomSheet.java:384`, `bottomSheet/AutoLoginBottomSheet.kt:430`).

**Request** (form, authpy @ 5d5758661c, `app.py:805-843`)

| Name           | In   | Type   | Required | Rules                                       |
| -------------- | ---- | ------ | -------- | ------------------------------------------- |
| `reference_id` | body | string | yes      | From [login-with-otp](#post-login-with-otp) |
| `code`         | body | string | yes      | The 6-digit code                            |

iOS also sends `send_via`; it is not read.

**Response** `200`: a [sign-in result](#sign-in-result-object) without `temporary`; fresh tokens.

**Errors** (`model/feature_user_auth.py:648-749`), checked in this order: "invalid reference", "code has been used/revoked", "invalid code", "code expired". The expiry is checked after the code.

**Side effects:**

* Marks the code row used. The update does not require the row to be unused, so two calls at the same moment can both sign in.
* Sets `loginType` to `email` or `mobile`, updates the login count and time, and stores the tokens and device info, as [/login](#post-login) does.

## GET /web-gsm-status

Tells the web whether sign-up by phone number is switched on.

* **Auth:** as [mobile-gsm-status](#get-mobile-gsm-status) (authpy @ 5d5758661c, `app.py:877-903`).
* **Used by:** web\_payments sign-up (web\_payments @ 7c2c3ddffd, `src/app/pages/auth/pay/components/pay-user-register/pay-user-register.component.ts:219`, through `src/app/services/auth/auth.service.ts:78-82`).

**Response:** as [mobile-gsm-status](#get-mobile-gsm-status), from its own setting.

## POST ?action=edit\_user\_password\_v7

Changes a user's password after checking the old one.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action acts on the `user_uuid` in the body, not on the token's user; the old password is the only proof.
* **Used by:**
  * iOS `APIManager.edituserPassword` when the password is not temporary: "My settings" (`SnapFix/MySettingsVC.swift:1042`) and the update-password screens outside the `.updatePassword` mode (`SnapFix/UpdatePasswordVC.swift:358`, `SnapFix/UpdatePassword/UpdatePasswordVC.swift:306`). It posts JSON (ios @ aa31967ac8, `APIManagers/APIManager.swift:1071-1076`).
  * Android "My profile" and the site list's password change (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/MyProfileActivity.kt:1269`, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:3345`), through `ApiUtils.doPost`, which posts JSON (`app/src/main/java/gmail/com/snapfixapp/utils/ApiUtils.java:58-83`).

**Request** (JSON body)

| Name           | In   | Type   | Required | Rules                                                                                                                                |
| -------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `user_uuid`    | body | string | yes      | The user to change. Unknown: "Invalid user!"                                                                                         |
| `password_old` | body | string | yes      | Checked against the account's phone number when it has one, otherwise its email, otherwise its staff username. Wrong: "invalid user" |
| `password_new` | body | string | yes      | At least 8 characters after trimming; otherwise "Password should have minimum 8 alphanumberic charecters!"                           |

**Response** `200`

```json
{ "result": true, "message": "Password update successful.", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false` and one of: "Password should have minimum 8 alphanumberic charecters!", "Invalid parameters.", "Invalid user!", "invalid user", "Password hash not found!". An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2654-2661`; `htmlphp/api/snapfix/class/cognito.functions.php:307-312`; `htmlphp/api/snapfix/class/class.functions.php:11075-11081`, `:11095-11150`).

**Side effects:**

* Stores the new salted hash on [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) and sets its `fPassword` to `--disabled--`.
* Writes a [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row with the username and the new password in plain text.

## POST ?action=forgotpassword\_v7

Resets the password of the account that owns an email or phone number, and sends the new password to it.

* **Auth:** the shared Basic login (`AUTH_USERNAME`): the action is on the no-token list, and the Basic login is checked for it whether or not `JWT_AUTH_ENABLED` is on (php-apis @ 238ca4414e, `html/api/snapfix/index.php:355`, `:434-481`). See [Basic logins](https://docs.snapfix.com/engineering-reference/api.md#basic-logins).
* **Used by:** authpy's [`/forgotpassword-v7`](#post-forgotpassword-v7), which iOS and Android call. authpy posts the app's JSON with its Basic login and adds `SP_FORWARDED_FOR`, the caller's `X-Forwarded-For` (authpy @ 5d5758661c, `app.py:485-503`, `model/feature_php_api.py:56-87`).

**Request** (JSON body)

| Name                | In   | Type   | Required | Rules                                                                                                                                                                                                                                   |
| ------------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username_estimate` | body | string | yes      | An email matches `fUsername` exactly. Anything numeric once `+` is removed counts as a phone number and matches any live account whose `fMobile` ends with the value, then country code plus number. Anything else gives "invalid user" |
| `SP_FORWARDED_FOR`  | body | string | no       | Added by authpy                                                                                                                                                                                                                         |

Because a phone number matches by its ending, a few digits are enough to reset the password of the one account whose number ends with them.

**Response** `200`

```json
{ "result": true, "message": "New password emailed successfully!", "serverTs": 1794387595000 }
```

For a phone number the message is "New password sent as SMS successfully!".

**Errors:** `200` with `result` `false` and one of: "Invalid parameters.", "invalid user", "Duplicate Email.", "Duplicate Mobile.", "invalid username.", "invalid mobile.", "Failed to send email!", "Failed to send sms!" or the SMS service's error text. The answer tells the caller whether the email or number has an account \[[ASK-228](https://github.com/snapfix/docs/blob/main/ASK.md#ask-228-should-sign-in-tell-an-unknown-contact-from-a-wrong-password)]. An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2630-2637`; `htmlphp/api/snapfix/class/cognito.functions.php:295-297`; `htmlphp/api/snapfix/class/class.functions.php:10980-10991`, `:11807-11934`).

**Side effects** (`class.functions.php:12131-12177`):

* Sets a random 6-character password of digits and lowercase letters on [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md).
* Sets `fPassword` to `--disabled--`, `temp_password` to 1 and `temp_password_required` to 1 on [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md).
* Emails or texts the new password in plain text. Anyone who knows a user's email or number can change that user's password.

## POST ?action=forgotpassword\_v8

Sends a password reset link to the email or phone number of an account. The password doesn't change here.

* **Auth:** the shared Basic login (`AUTH_USERNAME`), as for [`forgotpassword_v7`](#post-actionforgotpassword_v7).
* **Used by:** authpy's [`/forgotpassword-v8`](#post-forgotpassword-v8), which iOS and Android call. authpy posts JSON with its Basic login and adds `SP_FORWARDED_FOR` (authpy @ 5d5758661c, `app.py:510-528`, `model/feature_php_api.py:56-87`).

**Request** (JSON body)

| Name                | In   | Type   | Required | Rules                                                               |
| ------------------- | ---- | ------ | -------- | ------------------------------------------------------------------- |
| `username_estimate` | body | string | yes      | Matched as for [`forgotpassword_v7`](#post-actionforgotpassword_v7) |
| `origin`            | body | string | yes      | Stored on the link                                                  |
| `SP_FORWARDED_FOR`  | body | string | no       | Added by authpy                                                     |

**Response** `200`

```json
{ "result": true, "message": "Password reset link sent to email successfully!", "serverTs": 1794387595000 }
```

For a phone number the message is "Password reset link sent as SMS successfully!".

**Errors:** `200` with `result` `false` and one of: "Invalid parameters.", "invalid user", "Duplicate Email.", "Duplicate Mobile.", "invalid username.", "invalid mobile.", "Failed to send password reset link to email!", "Failed to send password reset link as SMS!". An empty body answers `result` `false` with "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2638-2645`; `htmlphp/api/snapfix/class/class.functions.php:11935-12130`).

**Side effects:**

* Inserts a [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md) row of type `reset_password`, titled "Reset Password", with the user, `origin`, `tx_type` `email` or `sms` and use counts at 0. Its short URL is the dynamic link domain plus the row's UUID (`class.functions.php:11986-12006`).
* Emails or texts the link. authpy's [`/dl-ctx/{dynamicLinkUUID}`](#get-dl-ctxdynamiclinkuuid) opens it, and refuses a reset link that is more than 15 minutes old or already used (authpy @ 5d5758661c, `model/feature_token_ops.py:3586-3597`).

## POST ?action=generate\_code\_v7

Sends a 6-character code to the account's own email or phone number, to verify it.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action acts on the `user_uuid` in the body.
* **Used by:**
  * iOS `OTPService` (ios @ aa31967ac8, `SnapFix/Forgot Password/OTPService.swift:230`), posting JSON through `apiCallWithUrlString` (`APIManagers/APIManager.swift:1385-1400`).
  * Android's code dialog, `callGenerateCodeApi` (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/dialog/VerifyOtpDialog.java:519-537`, called from `:191`, `:198`, `:305`, `:379`), a JSON POST (`app/src/main/java/gmail/com/snapfixapp/network/ApiService.java:482-484`).

**Request** (JSON body)

| Name                      | In   | Type   | Required     | Rules                                                             |
| ------------------------- | ---- | ------ | ------------ | ----------------------------------------------------------------- |
| `user_uuid`               | body | string | yes          | Unknown: "invalid user"                                           |
| `generate_type`           | body | string | yes          | `email` or `mobile`; anything else gives "invalid type to verify" |
| `fUsername`               | body | string | for `email`  | Must equal the account's email: "fUsername does not match"        |
| `fCountryCode`, `fMobile` | body | string | for `mobile` | Must equal the account's: "Mobile does not match"                 |

**Response** `200`

```json
{ "result": true, "message": "Verification Code Sent successfully!", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false` and one of: "Invalid parameters", "invalid parameters", "invalid type to verify", "invalid user", "Email has already been verified", "Mobile has already been verified", "fUsername does not match", "Mobile does not match", "Failed to send sms!". An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2614-2621`; `htmlphp/api/snapfix/class/cognito.functions.php:258-260`; `htmlphp/api/snapfix/class/class.functions.php:11573-11678`).

**Side effects:**

* Inserts a [`credential_code`](https://docs.snapfix.com/engineering-reference/db/tables/credential_code.md) row with the user, the email or phone number and the code in plain text. The code is random digits and lowercase letters.
* Emails the code, or texts "Your Snapfix verification code is …".
* Writes a [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row with the request.

## POST ?action=generate\_code\_v8

Sends a verification code like [`generate_code_v7`](#post-actiongenerate_code_v7), and also to an email or phone number the account doesn't have yet.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action acts on the `user_uuid` in the body.
* **Used by:** both apps under the registry name `generate_code_v8_profile` (ios @ aa31967ac8, `APIManagers/ApiEndpointManager.swift:2371-2372`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/APIEndPointUtils.java:419`):
  * iOS `SnapFix/Forgot Password/OTPService.swift:159`, the QR sign-up (`SnapFix/Sign up/SignUpVC.swift:289`) and the reset link screen (`SnapFix/Sign up/Reset password/ResetPasswordLinkVC.swift:234`). `SnapFix/ConfirmPopupRegVC.swift:252` calls it too, but nothing opens that screen.
  * Android profile check (`app/src/main/java/gmail/com/snapfixapp/bottomSheet/VerifyEmailMobileBottomSheet.kt:239`) and the set-password screens (`app/src/main/java/gmail/com/snapfixapp/activity/CreateNewPasswordActivity.kt:626`, `app/src/main/java/gmail/com/snapfixapp/activity/InvitedUserCreateNewPasswordActivity.kt:536`, `app/src/main/java/gmail/com/snapfixapp/activity/ResetPasswordSetNewPasswordActivity.kt:470`).

**Request:** the fields of [`generate_code_v7`](#post-actiongenerate_code_v7). The email or number need not match the account:

* When it differs from the account's, the action refuses it if any other account has it, deleted accounts included: "This email address is already in use", "This mobile number is already in use". Otherwise it sends the code to the new address.
* "Email has already been verified" and "Mobile has already been verified" apply only while the account's `temp_password` isn't 1.

**Response and errors:** as for [`generate_code_v7`](#post-actiongenerate_code_v7), plus the two "already in use" messages. An empty body answers `result` `false` with "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1183-1190`; `htmlphp/api/snapfix/class/cognito.functions.php:266-268`; `htmlphp/api/snapfix/class/class.functions.php:38160-38236`).

**Side effects:** as for [`generate_code_v7`](#post-actiongenerate_code_v7). With [`verify_code_v8`](#post-actionverify_code_v8), a caller can put an address they control on another user's account.

## POST ?action=register\_new\_user\_sso

Creates the account of a person who signed in with Apple, Google or Microsoft for the first time.

* **Auth:** the shared Basic login (`AUTH_USERNAME`), as for [`forgotpassword_v7`](#post-actionforgotpassword_v7).
* **Used by:** authpy's [`/sso-apple`](#post-sso-apple), [`/sso-google`](#post-sso-google) and [`/sso-azure`](#post-sso-azure), when no account has the email. authpy posts form fields with its Basic login, then signs the new user in (authpy @ 5d5758661c, `model/feature_user_auth.py:2275`, `:2711`, `:3157`).

**Request** (form fields; the action reads `$_POST`)

| Name                                                                                      | In   | Type        | Required | Rules                                                                                                                                                               |
| ----------------------------------------------------------------------------------------- | ---- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name_of_user`                                                                            | body | string      | yes      | Display name                                                                                                                                                        |
| `email`                                                                                   | body | string      | yes      | Must be a valid email that no live account has: "Invalid Email Address!", "Email already exists!"                                                                   |
| `sso_source`                                                                              | body | string      | yes      | The provider                                                                                                                                                        |
| `fFirstName`, `fLastName`, `fImage`, `fOrigin`                                            | body | string      | no       | Stored on the user                                                                                                                                                  |
| `sso_groups`                                                                              | body | JSON string | no       | A list of `{ "group", "userbusiness_template" }` the provider's groups map to; the user joins the valid ones                                                        |
| `ctx`                                                                                     | body | string      | no       | An invitation link; the user joins its invitations ([`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md)) |
| `account_and_product_updates`, `terms_and_conditions_agreed`, `terms_and_conditions_text` | body | string      | no       | Logged as consent                                                                                                                                                   |
| `SP_FORWARDED_FOR`                                                                        | body | string      | no       | Added by authpy                                                                                                                                                     |

**Response** `200`: the new user's ID and the app's first data. authpy reads both.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": { "uuid_tUser": "{uuid}", "table_data": {} }
}
```

**Errors:** `200` with `result` `false` and one of: "invalid params" (a missing required field), "Invalid Email Address!", "Email already exists!", "Parent data failed : …", "User Parent Creation Error : …". An empty form answers "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1309-1316`; `htmlphp/api/snapfix/class/class.functions.php:34414-34853`).

**Side effects:**

* Creates the user without a password, with `email_verified` 1.
* Adds the user to the groups of the email's pending [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) rows (marked processed), of the `ctx` invitations and of `sso_groups`.
* With no group to join, creates a site named after the email, with its settings and the user as admin ([`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md), [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md), [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md)), and copies the "How to use Snapfix" group into it.
* Writes [`tPri_Log_UserTermsConditions`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_usertermsconditions.md) and [`tPri_Log_UserGdpr`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_usergdpr.md) rows, and sends the contact to HubSpot.

## POST ?action=register\_new\_user\_v10

Creates the account held on a verified QR sign-up link.

* **Auth:** the shared Basic login (`AUTH_USERNAME`), as for [`forgotpassword_v7`](#post-actionforgotpassword_v7).
* **Used by:** authpy's [`/dl-ctx/{dynamicLinkUUID}`](#get-dl-ctxdynamiclinkuuid), when a `verify_profile` link is opened. authpy posts the sign-up form stored on the link (`reg_payload`) as form fields. On success it adds 1 to the original invitation link's use count and sends the inviter an acknowledgement (authpy @ 5d5758661c, `model/feature_token_ops.py:3600-3612`, `model/feature_php_api.py:157-158`).

**Request** (form fields; the action reads `$_POST`)

| Name                                                                                      | In   | Type   | Required                                      | Rules                                                                                                                  |
| ----------------------------------------------------------------------------------------- | ---- | ------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `name_of_user`                                                                            | body | string | yes                                           | Display name                                                                                                           |
| `email`                                                                                   | body | string | one of `email` or `country_code` and `mobile` | Must be valid and unused: "Invalid Email Address!", "Email already exists!"                                            |
| `country_code`, `mobile`                                                                  | body | string | see `email`                                   | Checked with the phone check (`validateMobileNumber`); in use: "Mobile Number already exists!"                         |
| `password_new`                                                                            | body | string | yes                                           | Not blank; no other rule                                                                                               |
| `dynamiclinkUUID`                                                                         | body | string | yes                                           | The live `verify_profile` link; otherwise "Invalid invitation!"                                                        |
| `fFirstName`, `fLastName`, `fImage`, `fOrigin`, `origin`                                  | body | string | no                                            | Stored on the user and a new site                                                                                      |
| `verification_code_uuid`                                                                  | body | string | no                                            | The [`api_token_auth`](https://docs.snapfix.com/engineering-reference/db/tables/api_token_auth.md) row to mark deleted |
| `account_and_product_updates`, `terms_and_conditions_agreed`, `terms_and_conditions_text` | body | string | no                                            | Logged as consent                                                                                                      |

**Response** `200`: who was registered, for authpy's answer to the app.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "type": "verify_profile",
    "payload": { "fUsername": "jane@example.com", "fCountryCode": "", "fMobile": "", "fFirstName": "Jane", "fLastName": "Doe" }
  }
}
```

**Errors:** `200` with `result` `false` and one of: "invalid params" (a missing required field), "Invalid invitation!", "Invalid Email Address!", "Email already exists!", "Mobile Number already exists!", the phone check's message, "Invalid parameters.". An empty form answers "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1656-1663`; `htmlphp/api/snapfix/class/cognito.functions.php:245-255`; `htmlphp/api/snapfix/class/class.functions.php:26268-26795`).

**Side effects:**

* Creates the user with the hashed password, and `email_verified` or `mobile_verified` 1 according to the link's `tx_type`.
* Clears the link's `reg_payload`, which held the password in plain text, and sets its use count to 1 (`class.functions.php:26490-26492`). Failed attempts leave it in place.
* Inserts a [`dynamiclink_user`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_user.md) row `onboarded`, and adds the user to the groups of the invitation the sign-up started from. With none, creates a site named after the email or phone number.
* Marks the email's [`group_invite`](https://docs.snapfix.com/engineering-reference/db/tables/group_invite.md) rows processed and the `verification_code_uuid` row deleted, writes the consent logs and sends the contact to HubSpot.

## POST ?action=resetpassword\_staffusername\_v7

Records a staff user's request to have the site admin reset their password.

* **Auth:** the shared Basic login (`AUTH_USERNAME`), as for [`forgotpassword_v7`](#post-actionforgotpassword_v7).
* **Used by:** authpy's [`/resetpassword-staffusername-v7`](#post-resetpassword-staffusername-v7), which skips authpy's IP block (authpy @ 5d5758661c, `app.py:535-549`). The apps' URL for it ends with a space.

**Request** (JSON body)

| Name             | In   | Type   | Required | Rules                            |
| ---------------- | ---- | ------ | -------- | -------------------------------- |
| `staff_username` | body | string | yes      | Blank: "invalid staff\_username" |

**Response** `200`

```json
{ "result": true, "message": "Your request has been recorded and your admin will change your password. Please liaise with your admin for further information.", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false` and one of: "invalid staff\_username", "username duplicate found. Please contact your admin to get it sorted.", "username not found.", "Your record has been deleted. Please contact your admin.". The answers tell whether a staff username exists. An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2703-2710`; `htmlphp/api/snapfix/class/cognito.functions.php:274-293`).

**Side effects:** sets `request_password_reset` to 1 and the request time on the staff user's [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row.

## POST ?action=save\_pri\_user\_auth\_v7

Changes the email and phone number a user signs in with, after checking the password, and signs the user in again.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action acts on the `user_uuid` in the body; the password is the proof.
* **Used by:**
  * iOS "My settings" and the profile screen (ios @ aa31967ac8, `SnapFix/MySettingsVC.swift:1617`, `SnapFix/New Profile/Profile/ViewModels/ProfileViewModel.swift:290`).
  * Android "My profile" (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/MyProfileActivity.kt:1933`).

**Request** (JSON body). All five fields must be sent, or the answer is "invalid params".

| Name                      | In   | Type   | Required | Rules                                                                                                                                                                                                                                                         |
| ------------------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_uuid`               | body | string | yes      | Unknown: "invalid user"                                                                                                                                                                                                                                       |
| `fUsername`               | body | string | yes      | The new email; blank removes it. Must be valid ("invalid email") and not on another live account ("Email already exists!")                                                                                                                                    |
| `fCountryCode`, `fMobile` | body | string | yes      | The new phone number; both `0` remove it, but only if an email stays ("For resetting mobile, you should keep a valid email!"). Must be numeric ("invalid mobile"), pass the phone check, and not be on another live account ("Mobile Number already exists!") |
| `fPassword`               | body | string | yes      | The current password, checked against the account's current email or phone number. It isn't changed                                                                                                                                                           |

**Response** `200`: authpy's [`/login`](#post-login) answer for the new username and the password, with new tokens.

**Errors:** `200` with `result` `false` and one of the messages above, the password check's message, "invalid user to update" or "failed to update user data". An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2686-2693`; `htmlphp/api/snapfix/class/cognito.functions.php:402-419`, `:565-716`).

**Side effects:**

* Updates `fUsername`, `fCountryCode` and `fMobile` on [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md); blank or `0` becomes empty. A changed email resets `email_verified` to 0, a changed phone number `mobile_verified`.
* Queues the change for the user's devices, then calls authpy's `/login` with authpy's own Basic login.

## POST ?action=set\_user\_password\_v8

Sets a user's password, without the old one, when the token is fresh.

* **Auth:** user token. The action itself decodes the Bearer JWT with php-apis's secret. The token needs the `fresh` claim ("You are not allowed to do this operation with the current token"), and its user (`identity` or `sub`) must be `user_uuid` ("You are not allowed to change someone's password").
* **Used by:** Android "My profile" and the site list's password change (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/MyProfileActivity.kt:1449`, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:3413`). iOS always asks for [`set_user_password_v9`](#post-actionset_user_password_v9) instead.

**Request** (JSON body)

| Name           | In   | Type   | Required | Rules                    |
| -------------- | ---- | ------ | -------- | ------------------------ |
| `user_uuid`    | body | string | yes      | The token's user         |
| `password_new` | body | string | yes      | Not blank; no other rule |

**Response** `200`

```json
{ "result": true, "message": "Password update successful.", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false` and one of: "invalid params", "invalid user", "You are not allowed to do this operation with the current token", "You are not allowed to change someone's password", "Password hash not found", or the JWT library's message for a bad token. An empty body answers "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1861-1869`; `htmlphp/api/snapfix/class/cognito.functions.php:1065-1127`).

**Side effects:**

* Stores the new hash on [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md) and sets its `fPassword` to `--disabled--`; sets `temp_password` to 0 on [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md).
* Writes a [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row with the username and the new password in plain text.

## POST ?action=set\_user\_password\_v9

Sets a user's password, without the old one, at the end of an invitation, sign-up or reset link.

* **Auth:** user token, decoded and checked by the action as for [`set_user_password_v8`](#post-actionset_user_password_v8), but the `fresh` check is commented out, so any valid token of the user works.
* **Used by:**
  * web\_app\_v2's set-password page (`/auth/set-password`), with the access token authpy gave for the link (web\_app\_v2 @ 0989b8e685, `src/app/services/auth/auth-http.service.ts:171-187`, `src/app/pages/auth/set-password/set-password.component.ts:110`).
  * iOS `APIManager.edituserPassword` for a temporary password: choose-password, QR sign-up, reset link and the update-password screens in `.updatePassword` mode (ios @ aa31967ac8, `SnapFix/ChoosePasswordVC.swift:208`, `SnapFix/Sign up/SignUpVC.swift:254`, `SnapFix/Sign up/Reset password/ResetPasswordLinkVC.swift:199`).
  * Android's set-password screens (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/CreateNewPasswordActivity.kt:522`, `app/src/main/java/gmail/com/snapfixapp/activity/InvitedUserCreateNewPasswordActivity.kt:432`, `app/src/main/java/gmail/com/snapfixapp/activity/ResetPasswordSetNewPasswordActivity.kt:366`), a JSON POST (`app/src/main/java/gmail/com/snapfixapp/network/ApiService.java:548-550`).

**Request** (JSON body)

| Name           | In   | Type   | Required | Rules                          |
| -------------- | ---- | ------ | -------- | ------------------------------ |
| `user_uuid`    | body | string | yes      | The token's user               |
| `password_new` | body | string | yes      | Not blank; no other rule       |
| `ctx`          | body | string | no       | The link the flow started from |

**Response** `200`

```json
{ "result": true, "message": "Password update successful.", "serverTs": 1794387595000 }
```

**Errors:** as for [`set_user_password_v8`](#post-actionset_user_password_v8), without the fresh-token and "Password hash not found" messages (php-apis @ 238ca4414e, `html/api/snapfix/index.php:955-962`; `htmlphp/api/snapfix/class/cognito.functions.php:1129-1215`).

**Side effects:**

* Stores the new hash on [`tPri_UserHashSalt`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userhashsalt.md), inserting the row when the user has none; sets `temp_password` to 0. Writes no password log.
* With `ctx`, adds 1 to that [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md)'s use count and sends the inviter an acknowledgement.

## POST ?action=validate\_usernames

Tells which emails and phone numbers in a list belong to Snapfix accounts, for adding people from the phone's contacts.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action reads the user from the token without checking its signature, and answers "invalid access!" when there is none.
* **Used by:**
  * iOS "Add from contacts" (ios @ aa31967ac8, `SnapFix/AddUserToGroupVC/AddFromContactVC.swift:409`). The name has no registry entry, so it goes to php-apis (`APIManagers/ApiEndpointManager.swift:33-55`).
  * Android add-from-contacts and group management (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/AddUserFromContactListActivity.kt:213-216`, `app/src/main/java/gmail/com/snapfixapp/activity/ManageGroupActivity.java:860-863`), a JSON POST (`app/src/main/java/gmail/com/snapfixapp/network/ApiService.java:422-424`). Android has no registry entry either; its URL comes from a build setting outside the repo \[[ASK-227](https://github.com/snapfix/docs/blob/main/ASK.md#ask-227-which-host-does-android-call-for-validate_usernames)].

**Request** (JSON body)

| Name        | In   | Type             | Required | Rules                                                                    |
| ----------- | ---- | ---------------- | -------- | ------------------------------------------------------------------------ |
| `usernames` | body | array of strings | yes      | Emails and phone numbers; not an array: "invalid params!". No size limit |

Emails are matched in one query. Phone numbers are matched as the number, country code plus number, and those with `+` or a space. Other entries count as staff usernames and are never looked up, so they always come back as not found. Deleted accounts don't match.

**Response** `200`: one entry per username, with the whole matching [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": [
    { "username": "jane@example.com", "snapfix_user": true, "snapfix_user_data": { "uuid": "{uuid}", "fUsername": "jane@example.com" } },
    { "username": "+15550100", "snapfix_user": false, "snapfix_user_data": null }
  ]
}
```

**Errors:** `200` with `result` `false` and "invalid access!", "invalid params!" or, for an empty body, "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1111-1117`; `htmlphp/api/snapfix/class/class.functions.php:40299-40408`).

## POST ?action=verify\_code\_v7

Checks a code from [`generate_code_v7`](#post-actiongenerate_code_v7) and marks the email or phone number verified.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action acts on the `user_uuid` in the body.
* **Used by:** iOS `OTPService` (ios @ aa31967ac8, `SnapFix/Forgot Password/OTPService.swift:267`); Android's code dialog, `callVerifyCodeApi` (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/dialog/VerifyOtpDialog.java:568-590`, called from `:362`).

**Request** (JSON body)

| Name                      | In   | Type   | Required     | Rules                                                             |
| ------------------------- | ---- | ------ | ------------ | ----------------------------------------------------------------- |
| `user_uuid`               | body | string | yes          |                                                                   |
| `code`                    | body | string | yes          | Compared with the user's newest code for that channel             |
| `verify_type`             | body | string | yes          | `email` or `mobile`; anything else gives "invalid type to verify" |
| `fUsername`               | body | string | for `email`  | Must equal the code's email: "fUsername does not match"           |
| `fCountryCode`, `fMobile` | body | string | for `mobile` | Must equal the code's: "mobile details does not match"            |

A code stays valid for 30 days \[[ASK-31](https://github.com/snapfix/docs/blob/main/ASK.md#ask-31-should-profile-verification-codes-last-30-days)]. It isn't marked used, and wrong guesses aren't limited.

**Response** `200`

```json
{ "result": true, "message": "Code verified successfully", "serverTs": 1794387595000 }
```

**Errors:** `200` with `result` `false` and one of: "Invalid parameters", "invalid parameters", "invalid type to verify", "Code data not found!", "invalid code", "code expired", "fUsername does not match", "mobile details does not match". An empty body answers `{"success": "0", "message": "Data cannot be blank!"}` (php-apis @ 238ca4414e, `html/api/snapfix/index.php:2622-2629`; `htmlphp/api/snapfix/class/cognito.functions.php:262-264`; `htmlphp/api/snapfix/class/class.functions.php:11742-11805`).

**Side effects:**

* Sets `email_verified` or `mobile_verified` to 1 on [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md).
* Writes a [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row with the request, code included.

## POST ?action=verify\_code\_v8

Checks a code from [`generate_code_v8`](#post-actiongenerate_code_v8). When the code was sent to a new email or phone number, that address replaces the account's.

* **Auth:** user token (Bearer JWT, if `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)]). The action acts on the `user_uuid` in the body.
* **Used by:** both apps under the registry name `verify_code_v8_profile` (ios @ aa31967ac8, `APIManagers/ApiEndpointManager.swift:2379-2380`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/APIEndPointUtils.java:420`):
  * iOS `SnapFix/Forgot Password/OTPService.swift:195`, `SnapFix/Sign up/SignUpVC.swift:322` and `SnapFix/Sign up/Reset password/ResetPasswordLinkVC.swift:266`.
  * Android `app/src/main/java/gmail/com/snapfixapp/bottomSheet/VerifyEmailMobileBottomSheet.kt:340`, `app/src/main/java/gmail/com/snapfixapp/activity/CreateNewPasswordActivity.kt:694`, `app/src/main/java/gmail/com/snapfixapp/activity/InvitedUserCreateNewPasswordActivity.kt:604` and `app/src/main/java/gmail/com/snapfixapp/activity/ResetPasswordSetNewPasswordActivity.kt:538`.

**Request, response and errors:** as for [`verify_code_v7`](#post-actionverify_code_v7) \[[ASK-31](https://github.com/snapfix/docs/blob/main/ASK.md#ask-31-should-profile-verification-codes-last-30-days)]. An empty body answers `result` `false` with "Data cannot be blank!" (php-apis @ 238ca4414e, `html/api/snapfix/index.php:1191-1198`; `htmlphp/api/snapfix/class/cognito.functions.php:270-272`; `htmlphp/api/snapfix/class/class.functions.php:38238-38306`).

**Side effects:**

* When the code's email or phone number differs from the account's, writes it onto the account's [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row. Any signed-in user can do this for another user's ID, then reset that account's password through the new address.
* Sets `email_verified` or `mobile_verified` to 1.
* Writes a [`tPri_Log`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log.md) row with the request, code included.

## Sign-in result object

What `/login` and `/verify-otp` return at the top level of the envelope.

| Field           | Type    | Meaning                                                                                                                                                                                                                                                                                                                                                                                |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`  | string  | A fresh access token ([User tokens](https://docs.snapfix.com/engineering-reference/api.md#user-tokens))                                                                                                                                                                                                                                                                                |
| `refresh_token` | string  | A refresh token                                                                                                                                                                                                                                                                                                                                                                        |
| `user_data`     | object  | Every column of the user's [tPri\_User](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) row, `fPassword` included, plus `should_create_business` (`1` when the user has no group outside a personal site), `login_src` (`snapfix`), `snapfix_login_allowed` (`1`), `loginType` (`email`, `mobile` or `staff_username`) and, for `/login`, `admin_temp_password` |
| `temporary`     | boolean | `/login` only: the password is shorter than 8 characters                                                                                                                                                                                                                                                                                                                               |

## SSO result object

What the three SSO routes return (authpy @ 5d5758661c, `app.py:1647-1702`).

| Field                           | Type    | Meaning                                                                                                                                                                                                                    |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `new_user_registration`         | boolean | A new account was made                                                                                                                                                                                                     |
| `access_token`, `refresh_token` | string  | Fresh tokens; `logged_in_with` is `sso_apple`, `sso_google` or `sso_azure`                                                                                                                                                 |
| `data`                          | object  | For a new account, the tables php-apis `register_new_user_sso` returned; it always holds `user_data`, as in the [sign-in result](#sign-in-result-object) but with `login_src` the provider and `snapfix_login_allowed` `0` |

Side effects (`model/feature_user_auth.py:2032-3240`):

* The provider must be allowed for the email's domain by the SSO rules (`login_recommendation`); an unknown email is allowed.
* An email that belongs to an account whose email is not verified is refused, unless the account has a temporary password.
* A new user is registered through php-apis `register_new_user_sso` (with `ctx` when sent). An invited user, whose email is not verified but who has a temporary password, is signed in and gets `email_verified` `1`.
* Each sign-in adds a row to `sso_apple_user`, `sso_google_user` or `sso_azure_user`, whose `sso_payload` keeps the whole request, the provider's tokens included.

## Username check object

The `data` of the username checks, when they do not sign the user in (`model/feature_user_auth.py:780-1213`).

| Field                  | Type    | Meaning                                                                                                                                 |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `email` or `mobile`    | string  | The contact checked; for a staff username, `staff_username`                                                                             |
| `verified`             | integer | `email` and `mobile` only: `1` when that contact is verified                                                                            |
| `login_recommendation` | array   | `{ "source", "in_use" }` items: the sign-in methods (for example `apple`, `google`, `azure`) the SSO rules allow for the email's domain |

The message is " exist and verified", " exist, but not verified" or " exist". An unknown email whose domain has SSO rules answers `result` `true` with only `email` and `login_recommendation`, and the message "User account does not exist, but your business has a configuration …".

## Dynamic link context object

The `data` of [dl-ctx](#get-dl-ctxdynamiclinkuuid), by link type (`model/feature_token_ops.py:3546-3615`).

| Link type           | `data`                                                                                          | Message                                                                                                         | Errors                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `qrcode-invitation` | `{ "type" }`                                                                                    | "Please create your profile to continue", or, for a signed-in user, the result of joining the invitation's site | "invitation expired" once the invitation is used                                 |
| `user-invitation`   | `{ "type", "payload" }`, with `fUsername`, `fCountryCode`, `fMobile`, `fFirstName`, `fLastName` | "Please set your password to continue"                                                                          | "invalid reference" unless the invited user is pending, existing or onboarded    |
| `reset_password`    | `{ "type", "payload" }`, with the same fields                                                   | "Please set your password to continue"                                                                          | "invalid reference" for a signed-in caller; "reference expired" after 15 minutes |
| `verify_profile`    | php-apis `register_new_user_v10`'s answer                                                       | "Verified successfully"                                                                                         | "invalid reference" without a stored form                                        |

Any other type answers "invalid loginType".


---

# 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/engineering-reference/api/auth.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.
