User access model
How HQ and franchisee users are scoped to locations, and why a franchisee has either one direct location or location groups, never both.
On this page
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 and connected AI apps. 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.