> For the complete documentation index, see [llms.txt](https://docs.widgelix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.widgelix.com/roles-and-permissions/user-guide.md).

# User Guide

### Table of contents

1. Overview
2. How permissions work
3. System roles
4. LoRaWAN permissions by role
5. Custom roles
6. Module permissions reference
7. Entity-level access
8. LoRaWAN entity restrictions
9. Assigning roles to users
10. Common permission scenarios
11. Limitations & best practices
12. Quick reference checklist

***

### Overview

The platform uses **role-based access control (RBAC)** to manage what each user can see and do within an organization.

Each user is assigned one role per organization. The role determines:

* Which sections appear in the sidebar (**menu access**)
* What actions the user can perform in each module (**module permissions**)
* Whether access is limited to specific items (**entity restrictions**)

Roles are managed from **Settings → Roles & Permissions**. User assignment is done from the **Organization** page.

***

### How permissions work

Permissions are organized in three layers:

```
Menu access        →  Which sections appear in the sidebar
        ↓
Module permissions →  What actions are allowed (Read / Write / Delete)
        ↓
Entity restrictions →  Optional allow-list for specific items
```

#### Menu access

Controls visibility of sidebar sections, including:

| Menu item          | Description                               |
| ------------------ | ----------------------------------------- |
| Organization       | Organization overview and user management |
| Solutions          | Solution management                       |
| Devices            | Device management                         |
| **LoRaWAN Server** | LoRaWAN Network Server                    |
| Events             | Organization events                       |
| Global Map         | Map view                                  |
| Global Dashboards  | Dashboard management                      |
| Project Repository | Project files                             |
| Device Types       | Device type configuration                 |
| Rule Engine        | Automation rules                          |
| Reports            | Report management                         |
| Settings           | Platform settings                         |

A user cannot use a module unless both the **menu item** and the corresponding **module permission** are granted.

#### Module permissions

Each module supports three actions:

| Action     | Allows                |
| ---------- | --------------------- |
| **Read**   | View existing items   |
| **Write**  | Create and edit items |
| **Delete** | Remove items          |

Modules include: Devices, Device Types, Rules, Solutions, Global Dashboards, Reports, Events, **LoRaWAN**, Project Repository, and Organization.

#### Entity restrictions

Optional rules that limit access to **specific items** within a module. When configured, the user can only access listed entities (allow-list model). See Entity-level access.

***

### System roles

Every organization has three built-in **system roles**. These cannot be edited or deleted.

| Role            | Summary                                                                      |
| --------------- | ---------------------------------------------------------------------------- |
| **Admin**       | Full access to all features, including LoRaWAN and user/role management      |
| **Contributor** | Can view and modify most resources; delete requires an extra toggle          |
| **Viewer**      | Read-only access to most modules; **no LoRaWAN or Events access by default** |

#### Admin

* Full access to everything in the organization
* Can manage users, roles, billing, and all LoRaWAN resources
* Can activate the LoRaWAN Network Server
* Can create, edit, and delete custom roles

#### Contributor

* Can read and write devices, solutions, rules, dashboards, reports, and **LoRaWAN** resources
* Can list users but cannot manage them by default
* **Delete** permission is controlled separately via the **Can delete** toggle when assigning the role

When **Can delete** is enabled for a Contributor, the user additionally receives delete permissions on all modules (including LoRaWAN) and can delete users.

#### Viewer

* Read-only access to most modules (devices, solutions, dashboards, etc.)
* **Does not** have LoRaWAN read, write, or delete permissions
* **Does not** have Events access
* Cannot activate the Network Server or modify any LoRaWAN resources
* Cannot manage users or roles

> To give a Viewer LoRaWAN or other restricted access, create a **custom role**.

***

### LoRaWAN permissions by role

| Action                                 | Admin | Contributor | Contributor + Can delete | Viewer |
| -------------------------------------- | :---: | :---------: | :----------------------: | :----: |
| See LoRaWAN Server menu                |   ✓   |      ✓      |             ✓            |   ✓\*  |
| View gateways, profiles, devices       |   ✓   |      ✓      |             ✓            |    ✗   |
| Activate Network Server                |   ✓   |      ✓      |             ✓            |    ✗   |
| Add / edit gateways, profiles, devices |   ✓   |      ✓      |             ✓            |    ✗   |
| Delete gateways, profiles, devices     |   ✓   |      ✗      |             ✓            |    ✗   |
| Manage roles & permissions             |   ✓   |      ✗      |             ✗            |    ✗   |

\* Viewers see menu items only if menu access is explicitly granted via a custom role, but still need module **Read** permission to view content.

For LoRaWAN setup and operation details, see LoRaWAN Network Server — User Guide.

***

### Custom roles

Administrators (or users with **Manage roles** permission) can create custom roles tailored to specific teams or workflows.

#### Where to manage roles

**Settings → Roles & Permissions**

This tab is visible only to users with the **Manage roles** permission.

#### Creating a custom role

1. Go to **Settings**.
2. Open the **Roles & Permissions** tab.
3. Click **Create role**.
4. Configure the role:

| Section                | Description                                        |
| ---------------------- | -------------------------------------------------- |
| **Name / Description** | Identify the role for your team                    |
| **Menu access**        | Which sidebar sections are visible                 |
| **Module permissions** | Read, Write, and/or Delete per module              |
| **Entity access**      | Optional restrictions to specific items            |
| **Users**              | User management permissions (list, manage, delete) |
| **Roles management**   | Allow this role to create and edit other roles     |

5. Click **Save**.

> **Note:** Module permissions for a section are only available when the corresponding **Menu access** checkbox is enabled. For example, LoRaWAN **Write** is available only when **LoRaWAN Server** menu access is checked.

#### Editing or deleting custom roles

* Custom roles can be edited or deleted from the roles table.
* **System roles** (Admin, Contributor, Viewer) cannot be modified or removed.
* A role in use by organization members should be reassigned before deletion.

#### User management permissions

| Permission       | Allows                              |
| ---------------- | ----------------------------------- |
| **List users**   | View the user list in Organization  |
| **Manage users** | Invite users and change their roles |
| **Delete users** | Remove users from the organization  |

#### Roles management permission

| Permission       | Allows                                |
| ---------------- | ------------------------------------- |
| **Manage roles** | Create, edit, and delete custom roles |

Users can only assign permissions they themselves hold. A Contributor with **Manage roles** cannot grant Admin-level permissions.

***

### Module permissions reference

| Module             | Read                             | Write                                  | Delete                  |
| ------------------ | -------------------------------- | -------------------------------------- | ----------------------- |
| Devices            | View devices                     | Add and edit devices                   | Remove devices          |
| Device Types       | View device types                | Add and edit device types              | Remove device types     |
| Rules              | View rules                       | Create and edit rules                  | Delete rules            |
| Solutions          | View solutions                   | Create and edit solutions              | Delete solutions        |
| Global Dashboards  | View dashboards                  | Create and edit dashboards             | Delete dashboards       |
| Reports            | View reports                     | Create and edit reports                | Delete reports          |
| Events             | View events                      | —                                      | Delete events           |
| **LoRaWAN**        | View gateways, profiles, devices | Activate server, add and edit entities | Delete LoRaWAN entities |
| Project Repository | View projects                    | Upload and edit projects               | Delete projects         |
| Organization       | View organization info           | Edit organization settings             | —                       |

***

### Entity-level access

For fine-grained control, a role can restrict access to **specific entities** instead of all items in a module.

#### Supported entity types

| Entity type                | Module             |
| -------------------------- | ------------------ |
| Device                     | Devices            |
| Device type                | Device Types       |
| Rule                       | Rules              |
| Solution                   | Solutions          |
| Global dashboard           | Global Dashboards  |
| Report                     | Reports            |
| Project                    | Project Repository |
| **LoRaWAN gateway**        | LoRaWAN            |
| **LoRaWAN device**         | LoRaWAN            |
| **LoRaWAN device profile** | LoRaWAN            |

#### How entity restrictions work

* **No entity rules configured** — the user can access **all** entities allowed by their module permissions.
* **Entity rules configured** — the user can access **only** the listed entities (allow-list).

For each entity rule, specify:

* **Entity type**
* **Entity** (select from a dropdown)
* **Allowed actions** (Read, Write, Delete — limited by module permissions)

#### Creating new entities with restrictions

If a role has **entity restrictions** for an entity type, the user **cannot create new** entities of that type. They can only work with entities explicitly listed in their rules.

To allow creating new items, either:

* Remove entity restrictions for that type, or
* Grant full module **Write** without entity rules

***

### LoRaWAN entity restrictions

LoRaWAN supports three entity types for fine-grained access control:

| Entity type                | Identified by | Example use case                              |
| -------------------------- | ------------- | --------------------------------------------- |
| **LoRaWAN gateway**        | Gateway ID    | Site technician manages one rooftop gateway   |
| **LoRaWAN device profile** | Profile ID    | Developer maintains a specific sensor profile |
| **LoRaWAN device**         | DevEUI        | Installer registers devices at one location   |

#### Example: LoRaWAN operator role

A custom role for a field technician who should manage only one gateway:

| Setting            | Value                                  |
| ------------------ | -------------------------------------- |
| Menu access        | LoRaWAN Server ✓                       |
| LoRaWAN module     | Read ✓, Write ✓                        |
| Entity restriction | Gateway "Office-Roof-GW" → Read, Write |

This user can view and edit that gateway but cannot see or modify other gateways, profiles, or devices.

#### Example: Read-only network monitor

| Setting             | Value            |
| ------------------- | ---------------- |
| Menu access         | LoRaWAN Server ✓ |
| LoRaWAN module      | Read ✓ only      |
| Entity restrictions | None             |

This user can view all LoRaWAN entities but cannot activate the server, add items, or make changes.

***

### Assigning roles to users

Roles are assigned per organization from the **Organization** page.

#### Adding a new user

1. Go to **Organization**.
2. Click **Add user**.
3. Enter first name, last name, email, and select a **Role**.
4. For **Contributor** roles, optionally enable **Can delete**.
5. Save.

Custom roles appear in the dropdown with a **(custom)** suffix. System roles appear by name (Admin, Contributor, Viewer).

#### Changing an existing user's role

1. Go to **Organization**.
2. Find the user in the list.
3. Click **Change role**.
4. Select the new role. For Contributor, set **Can delete** if needed.
5. Save.

> **Who can manage users:** Requires **Manage users** permission, typically held by Admins.

***

### Common permission scenarios

#### Scenario 1: Network administrator

Needs full LoRaWAN control.

| Setting | Value                                                       |
| ------- | ----------------------------------------------------------- |
| Role    | **Admin** or custom role with LoRaWAN Read + Write + Delete |

#### Scenario 2: Device installer

Can register devices but should not delete anything.

| Setting             | Value            |
| ------------------- | ---------------- |
| Menu access         | LoRaWAN Server ✓ |
| LoRaWAN module      | Read ✓, Write ✓  |
| Entity restrictions | None             |

#### Scenario 3: Read-only network monitor

Can view LoRaWAN status but not make changes.

| Setting        | Value            |
| -------------- | ---------------- |
| Menu access    | LoRaWAN Server ✓ |
| LoRaWAN module | Read ✓ only      |

#### Scenario 4: Dashboard viewer (no LoRaWAN)

Should see device data but not network infrastructure.

| Setting | Value                                    |
| ------- | ---------------------------------------- |
| Role    | **Viewer** (default — no LoRaWAN access) |

#### Scenario 5: Regional gateway manager

Manages gateways at one site only.

| Setting             | Value                             |
| ------------------- | --------------------------------- |
| Menu access         | LoRaWAN Server ✓                  |
| LoRaWAN module      | Read ✓, Write ✓                   |
| Entity restrictions | Specific gateway(s) → Read, Write |

#### Scenario 6: Rule editor without LoRaWAN

Can manage automation rules but not network infrastructure.

| Setting             | Value           |
| ------------------- | --------------- |
| Menu access         | Rule Engine ✓   |
| Rules module        | Read ✓, Write ✓ |
| LoRaWAN Server menu | ✗               |

***

### Limitations & best practices

#### Limitations

* System roles (**Admin**, **Contributor**, **Viewer**) cannot be customized.
* Billing and subscription management permissions are reserved for system administrators.
* Users can only assign permissions they themselves hold.
* Entity restrictions use an **allow-list** model — if any rules exist for a type, everything else is denied.
* A role with entity restrictions cannot create new entities of the restricted type.

#### Best practices

1. **Follow least privilege** — grant only the permissions each user needs.
2. **Use custom roles** for teams with specific responsibilities instead of giving everyone Admin access.
3. **Use entity restrictions** for contractors or site-specific operators who should not see the entire organization.
4. **Keep Contributor delete off** unless the user genuinely needs to remove resources.
5. **Document custom roles** — use the Description field to explain who the role is for and what it allows.
6. **Review roles periodically** — remove or downgrade access when team members change roles or leave.
7. **Separate LoRaWAN access from data access** — not everyone who views device dashboards needs network server permissions.

***

### Quick reference checklist

#### Granting LoRaWAN access

* [ ] **LoRaWAN Server** enabled under Menu access
* [ ] **LoRaWAN → Read** for viewing
* [ ] **LoRaWAN → Write** for creating and editing
* [ ] **LoRaWAN → Delete** for removing entities
* [ ] Entity restrictions configured (if needed)
* [ ] Role assigned to user in Organization settings

#### Creating a custom role

* [ ] Name and description set
* [ ] Menu access configured
* [ ] Module permissions match intended actions
* [ ] Entity restrictions added (if needed)
* [ ] User/role management permissions granted only when required
* [ ] Role tested with a non-admin account before wide rollout

***

*This guide describes role and permission management in the platform UI. For LoRaWAN setup and operation, see* [*LoRaWAN Network Server*](/lorawan-network-server/user-guide.md) *— User Guide.*