> 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/how-the-apps-work/screens/console/username-sites.md).

# Username sites

{% 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)). Platforms: web. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/console/username-sites.md).
{% endhint %}

Admins of a few listed sites create username logins for staff who have no email address or phone number; each login belongs to one group.

* **Where:** web `/account/:id/staff` (Site Console, tab "Username Sites", between "Site Details" and "Users"). The tab and the page work only for the sites on a list built into the app (`BUSINESS_STAFF_ACCOUNTS`, nine sites at web\_app\_v2 @ 0989b8e685, `src/app/shared/config.ts:59`), and only for a user who is in the site's admin or user list \[[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)]. On any other site the tab is hidden, and the address reloads the browser on Site Details without loading the username list, as it did for the QA site. The page itself is described from the code only.
* **Who:** the route admits role "Admin" and group admins (`authAdminGuard`); anyone else goes to `/fix`. Only role "Admin" sees the explanation and "Add". The server lets any member of the site create a login, in any group, and list the logins.
* **Feature:** [Username logins](https://docs.snapfix.com/product/features/console/username-logins.md)

## Layout

One card titled "Username Sites".

1. **Explanation (role "Admin").** "Use username sites when you staff do not use email or phone numbers to create their own Snapfix sites."
2. **"Add" (role "Admin").** Disabled while the list loads. A divider follows.
3. **List.** One row per login, sorted by username: an avatar with the username's initials and the username. The list shows neither the group nor the role of a login.

## Inputs

The dialog "Add a new username site":

| Field         | Type           | Required | Default                                      | Rules and messages                                                                                                                                                                                                                                  |
| ------------- | -------------- | -------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Username \*" | Text           | Yes      | Empty                                        | Up to 70 characters; typing stops at 70. "Please enter a username" under the field when it is empty. Saved trimmed. A name already in use fails on the server with "Staff username already exists!". Some names the form accepts can never sign in. |
| Password      | Password field | Yes      | Empty                                        | A hint lists the rules: at least 8 characters, with a number, an uppercase letter and a lowercase letter.                                                                                                                                           |
| "Group \*"    | Select         | Yes      | Empty; disabled until the site's groups load | The site's groups. No message when empty.                                                                                                                                                                                                           |

"Add" stays disabled while the form is invalid, so the save-time alerts in the code ("Please enter a password", "Please enter a valid password", "Please choose a group") are not reached.

## Actions

| Action              | Who                        | What happens                                                                                                                                                                                                                                                                                                                                                                                | API                                                                                                            |
| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Load the list       | Role "Admin", group admins | Lists the site's username logins.                                                                                                                                                                                                                                                                                                                                                           | `GET /v1/app/staff-username`, in the [Users API](https://docs.snapfix.com/engineering-reference/api/users.md)  |
| Add                 | Role "Admin"               | Opens "Add a new username site" and loads the site's groups.                                                                                                                                                                                                                                                                                                                                | [`GET /v1/app/businesses`](https://docs.snapfix.com/engineering-reference/api/groups.md#get-v1appbusinesses)   |
| Add (in the dialog) | Role "Admin"               | Creates the login, which the server makes an admin of the chosen group \[[ASK-132](https://github.com/snapfix/docs/blob/main/ASK.md#ask-132-should-username-logins-be-admins-of-their-group)]. The button shows success, the dialog closes after 1.5 seconds and the username is added to the list on screen without a reload. A failure shows the API's message and the dialog stays open. | `POST /v1/app/staff-username`, in the [Users API](https://docs.snapfix.com/engineering-reference/api/users.md) |
| Cancel              | Role "Admin"               | Closes the dialog; disabled while saving.                                                                                                                                                                                                                                                                                                                                                   | None                                                                                                           |

## States

* **Loading:** a spinner in the list.
* **Empty:** "No data available".
* **Error:** a failed list load shows the API's message and leaves the list empty. A failed "Add" shows the API's message.
* **No permission:** group admins see the list without the explanation and "Add". Members who are neither role "Admin" nor group admins never reach the route.

## Dialogs and sheets

* **Add a new username site:** see [Inputs](#inputs), with "Cancel" and "Add".

## Platform differences

The apps have no screen for this. The calls are `GET` and `POST /v1/app/staff-username` in the [Users API](https://docs.snapfix.com/engineering-reference/api/users.md).


---

# 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/how-the-apps-work/screens/console/username-sites.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.
