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

# Username logins

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

Some **staff** have no email address or phone number of their own, so they cannot sign in with a contact. On a few sites, admins create a **username login** for each of them in the web Site Console's "Username Sites" tab. A login has a username and a password and is tied to one **group**, where it becomes an admin. The staff member then signs in with the username and the password. Staff here means the site's own workers, not Snapfix employees.

## Rules

* The tab shows only on the sites of a list built into the web app (nine sites), and only to a user in the site's admin or user list. On any other site the tab is hidden and its address reloads the browser on Site Details \[[ASK-126](https://github.com/snapfix/docs/blob/main/ASK.md#ask-126-should-the-username-sites-tab-depend-on-a-list-of-sites-built-into-the-web-app)] ([Username sites](https://docs.snapfix.com/how-the-apps-work/screens/console/username-sites.md)).
* The route admits role "Admin" and group admins; anyone else goes to `/fix`. Both see the list; only role "Admin" sees the explanation and "Add" ([Username sites](https://docs.snapfix.com/how-the-apps-work/screens/console/username-sites.md#actions)).
* A login needs a username, a password and a group. The username is trimmed and stops at 70 characters. The password needs at least 8 characters, with a digit, a lowercase and an uppercase letter; the form shows this as a hint, and the server checks the same rule ([Inputs](https://docs.snapfix.com/how-the-apps-work/screens/console/username-sites.md#inputs); api\_php\_live\_v2 @ ef3c4319f6, `CreateStaffUsernameRequest.php:18`).
* A username can belong to one live user only: the server refuses a repeat with "Staff username already exists!" ([Inputs](https://docs.snapfix.com/how-the-apps-work/screens/console/username-sites.md#inputs)).
* The new login becomes an admin of its group; the dialog does not say so \[[ASK-132](https://github.com/snapfix/docs/blob/main/ASK.md#ask-132-should-username-logins-be-admins-of-their-group)].
* The list shows the usernames sorted A to Z, without their group or role. A login cannot be edited or removed here ([Username sites](https://docs.snapfix.com/how-the-apps-work/screens/console/username-sites.md#layout)).
* The server lets any member of the site create a login, in any group it names, even one of another site, and lets any member list the logins.
* Staff sign in by typing the username in the sign-in screen's email field ([Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md)). Some usernames the form accepts can never sign in: names of digits only, names shaped like an email address, and names with a quote, a backtick, a semicolon or a hash.
* The web offers no password reset for a username login, and the apps' reset call for it has a space at the end of its URL ([Password reset](https://docs.snapfix.com/product/features/account/password-reset.md)).

## Flow

```mermaid
flowchart TD
    tab["Username Sites tab"] --> listed{"Site on the built-in list?"}
    listed -- no --> details["Address reloads on Site Details"]
    listed -- yes --> list["List of usernames"]
    list --> admin{"Role Admin?"}
    admin -- no --> view["List only"]
    admin -- yes --> add["Add: username, password and group"]
    add --> made["Login created as an admin of the group"]
    made --> signin["Staff member signs in with the username"]
```

## Platforms

| Capability                  | Web                     | iOS                     | Android |
| --------------------------- | ----------------------- | ----------------------- | ------- |
| See and add username logins | Yes, on listed sites    | No                      | No      |
| Sign in with a username     | Yes, in the email field | Yes, in the email field | Yes     |
| Reset a username's password | No                      | Fails                   | Fails   |

## Screens

* [Username sites](https://docs.snapfix.com/how-the-apps-work/screens/console/username-sites.md): the Site Console tab (web).
* [Sign-in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md): where staff type the username.

## API and data

* [Users API](https://docs.snapfix.com/engineering-reference/api/users.md): `GET /v1/app/staff-username` lists the site's logins, and `POST /v1/app/staff-username` creates one.
* The groups for the dialog: [`GET /v1/app/businesses`](https://docs.snapfix.com/engineering-reference/api/groups.md#get-v1appbusinesses).
* Tables: [`staff_username`](https://docs.snapfix.com/engineering-reference/db/tables/staff_username.md) (one row per login, with its creator), [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md) (the person, with the `staff_username` that sign-in reads) and [`tPri_UserBusiness`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userbusiness.md) (the group and its admin role).

## Depends on

* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): the sign-in path that reads the username.
* [Password reset](https://docs.snapfix.com/product/features/account/password-reset.md): the reset for these logins.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Group members](https://docs.snapfix.com/product/features/groups/group-members.md): the group each login is an admin of.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the site's other people.
* [Site details](https://docs.snapfix.com/product/features/console/site-details.md): where a site that is not on the list is sent.

## Edge cases

* **Duplicate username:** "Staff username already exists!", and the dialog stays open.
* **After "Add":** the dialog closes after 1.5 seconds and the username joins the list on screen, with a temporary ID until the page is opened again.
* **Errors:** a failed list load or "Add" shows the API's message ([States](https://docs.snapfix.com/how-the-apps-work/screens/console/username-sites.md#states)).
* **No logins:** the list shows "No data available".
* **Text:** the explanation reads "Use username sites when you staff do not use email or phone numbers…".


---

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

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

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

```
GET https://docs.snapfix.com/product/features/console/username-logins.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.
