> 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.*


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.widgelix.com/roles-and-permissions/user-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.