> 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/staff/staff-admin.md).

# Staff admin app

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

Snapfix employees, called **staff** here, look after customers in the **staff admin app** (`webadmin_angular`), a web app separate from the apps and the web app that customers use. Staff sign in with a username and password, and the app keeps a session only for users with the staff flag. The home page lists whom to call when the service has a problem, and the side menu leads to the staff tools: [customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md), [billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md), [usage dashboards](https://docs.snapfix.com/product/features/staff/usage-dashboards.md), [support tools](https://docs.snapfix.com/product/features/staff/support-tools.md), [survey setup](https://docs.snapfix.com/product/features/staff/survey-setup.md), [marketing popups](https://docs.snapfix.com/product/features/notifications/marketing-popups.md), [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md) and the Guestline page of [PMS integrations](https://docs.snapfix.com/product/features/integrations/pms-integrations.md). The tools change customer data directly and show every customer's data. A site's own workers who sign in with a username are a different group: see [Username logins](https://docs.snapfix.com/product/features/console/username-logins.md).

## Rules

### Signing in

* Staff sign in with the customers' sign-in service, sending the username and password with a Basic login built into the app. A blank field is refused in the browser with "Username and password are required." ([Log in](https://docs.snapfix.com/how-the-apps-work/screens/staff/sign-in.md#inputs)).
* Only a user whose `fSnapfixWebAdminUser` is 1 gets a session. Anyone else gets "The username or password is invalid." and nothing is stored, although the server has issued tokens: the check runs only in the browser ([Log in](https://docs.snapfix.com/how-the-apps-work/screens/staff/sign-in.md#actions)).
* A refused sign-in shows the sign-in service's own message, such as "Incorrect password" for a wrong password ([Log in](https://docs.snapfix.com/how-the-apps-work/screens/staff/sign-in.md#states)).
* The session (both tokens and the profile) sits in the tab's session storage, so it ends when the tab closes and each new tab signs in again. Any script running in the page can read it ([Log in](https://docs.snapfix.com/how-the-apps-work/screens/staff/sign-in.md#actions)).
* A call answered with `401` makes the app refresh the access token once and repeat the call. If the refresh is refused too, the session is removed and the app opens the sign-in page ([Staff screens](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#access)).
* "Log Out", the last menu item, clears the session and opens the sign-in page ([Log in](https://docs.snapfix.com/how-the-apps-work/screens/staff/sign-in.md#actions)).

### Pages and menu

* Every page but the sign-in needs a session: the route guard checks only that the browser holds both tokens and a user, and sends anyone else to the sign-in page. A signed-in user who opens the sign-in page goes to Home ([Staff screens](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#access)).
* So the guard checks the session, not the staff role. The pages themselves add no role check.
* "Credit Card Payment", "Stripe Payment" and "Paywall" also need a username on a list built into the app, and a token that names the user's own ID; anyone else goes to Home. Their menu items, and "Survey", show only to the listed staff, but the Survey page itself has no check, so its address opens for any session ([Staff screens](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#access)).
* The side menu shows once signed in, in seven groups ([Menu and frame](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#menu-and-frame)). Any address the app does not know opens Home.
* Outside production builds every page shows "This is TEST Environment." ([Menu and frame](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#menu-and-frame)).
* Pages that work on one site pick it with a shared account picker; each page keeps its own choice ([Account picker](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#account-picker)).

### What the server checks

* The Laravel `/v1/admin` routes check the staff flag on the server, and refuse a missing, deleted or non-staff user. Without the flag the answer is `400` "Something went wrong", not a staff message ([Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md)).
* Those routes skip the blocked-token, blacklist and temporary-password checks of the customer routes, so a blocked token works until it expires.
* Most php-apis actions and every apipy route that the pages call check no staff flag, so any signed-in Snapfix user could make those calls ([php-apis actions](https://docs.snapfix.com/engineering-reference/api/staff.md#php-apis-actions)). Each tool's feature doc says what its calls check.

### Home

* Home is the first page after signing in. It lists three staff contacts to call, in order, when anything is wrong with the service, and warns that the portal gives full, unfiltered access to all businesses and users. It makes no calls ([Home](https://docs.snapfix.com/how-the-apps-work/screens/staff/home.md)).
* The contacts' names and phone numbers are written into the page's code, so every visitor downloads them before signing in.

## Flow

```mermaid
flowchart TD
  open["Open the staff admin app"] --> session{"Tokens and user in this tab?"}
  session -- "no" --> login["Log in: username and password"]
  login --> answer{"Sign-in answer"}
  answer -- "refused" --> toast["Sign-in service's message"]
  answer -- "tokens, no staff flag" --> denied["The username or password is invalid."]
  answer -- "tokens, staff flag" --> home["Home"]
  session -- "yes" --> home
  home --> menu["Side menu"]
  menu --> kind{"Card, Stripe or Paywall page?"}
  kind -- "no" --> tool["The tool opens"]
  kind -- "yes" --> listed{"Username on the app's list?"}
  listed -- "yes" --> tool
  listed -- "no" --> back["Home"]
  menu --> out["Log Out clears the session"]
```

## Platforms

| Capability                             | Web                       | iOS | Android |
| -------------------------------------- | ------------------------- | --- | ------- |
| Sign in to the staff admin app         | Yes, staff flag only      | No  | No      |
| Home with the contacts and the warning | Yes                       | No  | No      |
| Side menu to the staff tools           | Yes                       | No  | No      |
| Card, Stripe, Paywall and Survey items | Yes, for listed usernames | No  | No      |

## Screens

* [Log in](https://docs.snapfix.com/how-the-apps-work/screens/staff/sign-in.md): the sign-in form, its messages and the session.
* [Home](https://docs.snapfix.com/how-the-apps-work/screens/staff/home.md): the contacts and the warning.
* The other pages are listed in the [staff screens index](https://docs.snapfix.com/how-the-apps-work/screens/staff.md); the Guestline page is in [Guestline](https://docs.snapfix.com/how-the-apps-work/screens/integrations/guestline.md).

## API and data

* [Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md): `POST /login` (authpy), the sign-in that the customer apps also use, and `POST /refresh`, which renews the access token.
* [Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md): the routes and actions the tools call, each with what it checks.
* Tables: [`tPri_User`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_user.md); `fSnapfixWebAdminUser` on the user row marks staff.

## Depends on

* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): the same sign-in service.
* The tools in the menu: [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md), [Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md), [Usage dashboards](https://docs.snapfix.com/product/features/staff/usage-dashboards.md), [Support tools](https://docs.snapfix.com/product/features/staff/support-tools.md) and [Survey setup](https://docs.snapfix.com/product/features/staff/survey-setup.md), and the staff pages of [Marketing popups](https://docs.snapfix.com/product/features/notifications/marketing-popups.md), [QR forms](https://docs.snapfix.com/product/features/qr/qr-forms.md) and [PMS integrations](https://docs.snapfix.com/product/features/integrations/pms-integrations.md).
* Outside services reached through the server: HubSpot, Stripe, GoCardless and Xero ([Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md)).

## Edge cases

* **A user without the staff flag:** the server issues tokens; only the browser refuses the session. With the tokens such a user could call the routes that check no staff flag.
* **Survey page by address:** it opens for any session; the card, Stripe and Paywall pages send an unlisted user to Home.
* **Expired session:** after a refused refresh the app opens the sign-in page.
* **New tab:** the session is per tab, so a new tab asks to sign in again.
* **Unknown address:** Home opens.
* **Offline and time zones:** not applicable to these pages.
* **Several sites:** the sign-in and Home have none; each tool picks its own site.


---

# 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/staff/staff-admin.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.
