# User access model

Every FranchiseSEE user has a **perspective** that decides how much of the brand they see, and a
**role** that decides what they can do.

## Perspectives

| Perspective | Sees |
|-------------|------|
| HQ (`franchisor`) | Every location in the brand |
| Franchisee (`franchisee`) | Only the locations assigned to them |

The same rule applies everywhere: in the web app, the [REST API](https://franchisesee.com/docs/api/getting-started.md) and
[connected AI apps](https://franchisesee.com/docs/ai/data-scope-and-permissions.md). A token or AI connection never sees more
than its user.

## How a franchisee gets locations

A franchisee's access comes from **exactly one** of two sources:

- **One direct location.** The user is assigned a single location. This suits a single-store
  operator.
- **One or more location groups.** A location group is a named set of locations (for example
  "Austin Metro"), and the user sees every location in every group they belong to. This suits a
  multi-store operator. Adding a store to the group gives every member access at once.

The two are **mutually exclusive**. A user has a direct location *or* location groups, never both:

- Assigning a direct location **clears** the user's location groups.
- Assigning location groups **clears** the user's direct location.

"Adding" groups keeps the user's other groups, but it still switches them off a direct location.

A franchisee with neither a location nor a group sees no store data until one is assigned.

### Setting access by API or AI

| To | REST API | Admin MCP tool |
|----|----------|----------------|
| Give a user one direct location | `PATCH /api/v1/users/{id}` with `location_id` | `update-user` |
| Replace all of a user's groups | `PUT /api/v1/users/{id}/location-groups` | `sync-location-groups-for-user` |
| Add groups to many users at once | `POST /api/v1/users/bulk-location-groups` | `bulk-add-location-groups-for-users` |
| Add groups to one user | | `add-location-groups-for-user` |
| Replace a location's groups | `PUT /api/v1/locations/{id}/location-groups` | `sync-location-groups-for-location` |

Each needs the *Manage Users* permission (or *Manage Locations* for a location's groups) and a token
with the `update` permission.

## Roles

Each perspective has two roles:

| Role | Perspective | Can |
|------|-------------|-----|
| User (`franchisor_user`) | HQ | View dashboards, analytics, reports and settings across the brand |
| Admin (`franchisor_admin`) | HQ | Everything a User can, plus manage users, locations, competitions, goals, API tokens, SSO and company settings |
| User (`franchisee_user`) | Franchisee | View their own stores' dashboards, analytics, risk flags and goals, export orders, propose goals |
| Admin (`franchisee_admin`) | Franchisee | The same as a franchisee User |

HQ admins can adjust which permissions each role carries in the brand's permission settings.

## With enterprise SSO

Users who sign in through your company's identity provider follow the same model. Invite them
first to set their perspective, role and locations before their first sign-in; see
[Enterprise SSO onboarding](https://franchisesee.com/docs/sso/enterprise-sso-onboarding.md).
