# Roles & permissions

Cuppa uses **two separate** role systems. Do not mix them up.

---

## 1. Global roles (admin panel)

**Menu:** System → **Roles**  
**URL:** `/dashboard/roles`

### What they control

Access to the **main admin panel**:

- Can this person view Users?
- Can they edit Businesses?
- Can they impersonate?

### Default global roles

| Role | Typical use |
|------|-------------|
| `SUPER_ADMIN` | Full access; cannot be restricted |
| `ADMIN` | Most admin tasks |
| `MANAGER` | Limited admin tasks |
| `USER` | Minimal or no admin access |

### Assign a global role

1. Open **Employees** or **Users**.
2. Edit the person.
3. Choose a role in the **Role** dropdown.
4. Save.

Or create/edit roles under **System → Roles** and tick permissions.

---

## 2. Business roles (inside one business)

**Menu:** Business panel → **Roles**  
**URL:** `/dashboard/business/roles`

### What they control

Access **inside one business**:

- Manage locations
- Manage staff
- View business settings

### Examples

- **Owner** — full control of that business
- **Manager** — locations + staff
- **Staff** — limited day-to-day access
- **Custom** — you define permissions

### Assign a business role

1. Open **Business → Staff** (or business detail members).
2. Add or edit a member.
3. Pick a **business role**.
4. Save.

---

## Side-by-side

| | Global role | Business role |
|---|-------------|-----------------|
| **Where set** | Employees / Users page | Business → Staff |
| **Where managed** | System → Roles | Business panel → Roles |
| **Scope** | Whole platform admin | One business |
| **Example** | `ADMIN` | `Manager` |

---

## Permissions list (global)

Common global permissions include:

| Permission | Allows |
|------------|--------|
| `USERS_VIEW` | See Employees & Users pages |
| `USERS_CREATE` | Add users |
| `ROLES_VIEW` | See Roles page |
| `BUSINESSES_VIEW` | See Businesses page |
| `BUSINESSES_IMPERSONATE` | Impersonate a business |
| `USERS_IMPERSONATE` | Impersonate a user |
| `SETTINGS_VIEW` | See Settings |

Super admin bypasses all checks.

---

## Create a custom global role

1. Go to **System → Roles**.
2. Click **Add role**.
3. Enter name and description.
4. Select permissions by module.
5. Save.
6. Assign the role on Employees or Users pages.

System roles (like `SUPER_ADMIN`) may be protected from editing.

---

## Common mistakes

| Mistake | Fix |
|---------|-----|
| Gave business Manager role on Users page | Business roles are set on **Business → Staff** |
| Staff can't access admin panel | They may only need **business role**, not global admin |
| Super admin permissions in business roles panel | Wrong panel — use **System → Roles** for global perms |
| Employee can't open Businesses | Edit global role; add `BUSINESSES_VIEW` |

---

## Related guides

- [Who is who?](./02-who-is-who.md)
- [Employees](./03-employees.md)
- [Business panel — Roles](./06-business-panel.md#roles-business)