> 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

Control who can see and do what in your organization with system roles, custom roles and per-entity restrictions.

The platform uses **role-based access control (RBAC)**. Each user has exactly one role per organization, and the role decides:

* which sections appear in the sidebar (**menu access**),
* what the user can do in each module (**Read / Write / Delete**),
* whether access is limited to specific items (**entity restrictions**).

Roles are managed in **Settings → Roles & Permissions**. Users are invited and assigned roles in the **Users** block of the **Overview** page.

***

## How permissions work

Permissions are organized in three layers:

```
Menu access          →  Which sections appear in the sidebar
        ↓
Module permissions   →  Read / Write / Delete for all items of a module
        ↓
Entity restrictions  →  Optional allow-list of specific items
```

* **Write** and **Delete** always require **Read**.
* A module's Read / Write / Delete can only be ticked when the section's **Menu** toggle is on.
* If a role has no entity restrictions, it applies to **all** items of the module.

***

## Roles & Permissions page

![Roles & Permissions tab](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2F7FohHcMBk66KjgWDVehO%2Froles-list.png?alt=media\&token=580e578a-bf97-4d9d-a579-fb0eaae7a787)

The table lists every role in the organization:

| Column       | Description                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------ |
| **Role**     | Role name and description.                                                                                   |
| **Type**     | **System** (built in, locked) or **Custom** (created by your team).                                          |
| **Sections** | Sections the role is limited to, if any.                                                                     |
| **Access**   | Number of permissions granted and the entity scope (**All entities**, or the number of entity restrictions). |

System roles show a lock icon and cannot be edited. Custom roles have **Edit** (pencil) and **Delete** (bin) buttons. Use **Fit screen / Expand** to switch the table width.

{% hint style="info" %}
The **Roles & Permissions** tab is visible only to users whose role has the **Manage roles** permission.
{% endhint %}

***

## System roles

Every organization has three built-in roles that cannot be changed or deleted.

| Role            | Summary                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------- |
| **Admin**       | Full access to everything, including LoRaWAN, users and roles.                                |
| **Contributor** | Read and write most resources. Deleting requires the extra **Can delete** toggle on the user. |
| **Viewer**      | Read-only access to most modules. **No LoRaWAN and no Events access** by default.             |

#### Admin

* Full access to everything in the organization.
* Manages users, roles, billing and all LoRaWAN resources, and can activate the LoRaWAN Network Server.

#### Contributor

* Reads and writes assets, solutions, actions, dashboards, reports and **LoRaWAN** resources.
* Can see the user list but cannot manage users by default.
* **Delete** is granted per user with the **Can delete** toggle (*Allow deleting assets, rules and dashboards*). See [Assigning roles to users](#assigning-roles-to-users).

#### Viewer

* Read-only access to assets, solutions, dashboards and similar modules.
* No LoRaWAN read / write / delete, no Events access, no user or role management.

> To give a Viewer-like user LoRaWAN or Events access, create a **custom role**.

***

## Creating a custom role

1. Go to **Settings → Roles & Permissions**.
2. Click **+ Create role**.
3. Work through the sections in the left navigation of the dialog: **General**, **Menu & modules**, **Entity access**, **Users**, **Roles management**.
4. Check the summary in the footer (*N permissions · N entity restrictions*) and click **Create role**.

### General

![Create role: General and the start of Menu & modules](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2F4fpDZNgwaSKClEEXfmns%2Frole-general.png?alt=media\&token=0d0bedb9-c449-4414-b00e-ff47c73aa500)

* **Name** (required): for example *Field Technician*.
* **Description**: who the role is for and what it allows. It is shown under the role name in the table.

### Menu & modules

![Menu & modules matrix](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2FRmXbgOCDZTvFfAxwqkJg%2Frole-modules.png?alt=media\&token=0c395171-a60c-432d-b136-5f259fee8100)

Each row is a section of the platform. For each one, choose:

| Column     | Effect                                                                            |
| ---------- | --------------------------------------------------------------------------------- |
| **Menu**   | Shows the section in the sidebar. Must be on before the checkboxes can be ticked. |
| **Read**   | View all items of the module.                                                     |
| **Write**  | Create and edit items (needs Read).                                               |
| **Delete** | Remove items (needs Read).                                                        |

**Map** and **Settings** are *Menu access only*: they have no Read / Write / Delete. The counter next to **Menu & modules** in the dialog navigation shows how many sections are enabled (e.g. 4/12).

In the example above, the *Field Technician* role can see Assets, Events, LoRaWAN and Map, may create and edit assets and LoRaWAN devices, and only view events. It cannot delete anything.

### Entity access

Entity access narrows a role from "all items of a module" to a short allow-list.

![Entity type list: types whose module has no Read are disabled](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2F7qNlHSQZjpHASxr1sbuW%2Frole-entity-types.png?alt=media\&token=2abf5404-0ce9-4d76-a953-1791efeeee82)

1. Select an **Entity type**. Types whose module has no **Read** permission are disabled and marked *needs module Read*.
2. Select the **Entity**.
3. Tick the **Allowed actions**. Only actions granted at module level are offered (e.g. Read and Write when the module has no Delete).
4. Click **+ Add restriction**. Repeat for more entities.

![Entity restriction added, and the Users section](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2FGYuiZNIK1a2jGN3hcMzo%2Frole-entity-users.png?alt=media\&token=6fddd824-3602-46e7-a06a-b2354a3e16fa)

Each restriction is shown as a card with the entity name, its type and the allowed actions. Use the bin icon to remove it.

### Users

| Permission       | Allows                                 |
| ---------------- | -------------------------------------- |
| **List users**   | See members of the organization.       |
| **Manage users** | Invite members and change their roles. |
| **Delete users** | Remove members from the organization.  |

### Roles management

| Permission       | Allows                                              |
| ---------------- | --------------------------------------------------- |
| **Manage roles** | Create, edit and delete roles on the Settings page. |

Users can only grant permissions they hold themselves, so a custom role with **Manage roles** cannot create a role with more rights than its own.

### Editing or deleting a custom role

* Click the pencil icon on a custom role to edit it in the same dialog.
* Click the bin icon to delete it. Reassign members who use the role first.
* System roles (Admin, Contributor, Viewer) cannot be edited or deleted.

***

## Module permissions reference

| Module                                         | Read                             | Write                                  | Delete                  |
| ---------------------------------------------- | -------------------------------- | -------------------------------------- | ----------------------- |
| Assets *(formerly Devices)*                    | View assets                      | Add and edit assets                    | Remove assets           |
| Asset Templates *(formerly Device Types)*      | View templates                   | Add and edit templates                 | Remove templates        |
| Actions *(formerly Rule Engine)*               | View actions                     | Create and edit actions                | Delete actions          |
| Solutions                                      | View solutions                   | Create and edit solutions              | Delete solutions        |
| Site Dashboards *(formerly 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         |
| Overview                                       | View organization overview       | Edit organization settings             | —                       |
| Map                                            | Menu access only                 |                                        |                         |
| Settings                                       | Menu access only                 |                                        |                         |

***

## Entity-level access

### Supported entity types

| Entity type                | Module             |
| -------------------------- | ------------------ |
| Device                     | Assets             |
| Device type                | Asset Templates    |
| Rule                       | Actions            |
| Solution                   | Solutions          |
| Site dashboard             | Site Dashboards    |
| Report                     | Reports            |
| Project                    | Project Repository |
| **LoRaWAN gateway**        | LoRaWAN            |
| **LoRaWAN device**         | LoRaWAN            |
| **LoRaWAN device profile** | LoRaWAN            |

### How restrictions work

* **No restrictions**: the user can access **all** entities allowed by the module permissions (*All entities* in the roles table).
* **Restrictions configured**: the user can access **only** the listed entities of that type (allow-list).
* A role with restrictions for an entity type **cannot create new** entities of that type. To allow creating, remove the restrictions for that type and rely on module **Write**.

### LoRaWAN entity restrictions

| Entity type                | Identified by | Example use case                               |
| -------------------------- | ------------- | ---------------------------------------------- |
| **LoRaWAN gateway**        | Gateway ID    | A site technician manages one rooftop gateway  |
| **LoRaWAN device profile** | Profile ID    | A developer maintains one sensor profile       |
| **LoRaWAN device**         | DevEUI        | An installer registers devices at one location |

For LoRaWAN setup, see [LoRaWAN Network Server](https://docs.widgelix.com/lorawan-network-server/overview.md).

***

## 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             |   ✓   |      ✗      |             ✗            |    ✗   |

\* Use a custom role with LoRaWAN **Menu** and **Read** to give read-only network access.

***

## Assigning roles to users

Users are managed in the **Users** block on the **Overview** page (*formerly Organization*). It requires **List users** to see the list and **Manage users** to invite or change roles.

![Users on the Overview page](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2FSrdvyo9pNtNlIdVByhzn%2Forg-users.png?alt=media\&token=b3cf8106-d5fd-4db3-9cf9-9dd781233f5e)

The list shows each member's name, online status, e-mail, role, and when they were last seen. Use the search box and the **Role** filter to find users. A small bin icon next to a **Contributor** badge means **Can delete** is enabled for that user. The pencil changes the role. The red bin removes the user from the organization (requires **Delete users**).

### Adding a user

1. Click **+ Add user**.
2. Enter **First name**, **Last name** and **E-mail**.
3. Choose a **Role**. Custom roles are listed with the **(custom)** suffix.

![Add user: role list](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2F0k1SuuncV4aORirA0WIa%2Fuser-add.png?alt=media\&token=cf41c317-5628-4a4f-a74b-65d3fef08b05)

4. For **Contributor**, decide whether to enable **Can delete** (*Allow deleting assets, rules and dashboards*).

![Add user with Contributor and the Can delete toggle](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2F4wVmPCUVdVWzph7m7PT6%2Fuser-add-contributor.png?alt=media\&token=ef976b5c-9112-4b66-92e3-632f65aa94f2)

5. Click **Send invitation**. The user receives an e-mail with a sign-in link.

### Changing a user's role

1. Click the pencil icon on the user's row.
2. In **Change role**, select the new role and, for Contributor, set **Can delete**.
3. Click **Save**.

![Change role dialog](https://2494440469-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fggsr9Xlsze5cwVr4WMof%2Fuploads%2Fn7Gn0H4Gr3oEUcYC27UU%2Fuser-change-role.png?alt=media\&token=f317c9ea-542b-42a6-b3de-001feaf27837)

***

## Common scenarios

| Scenario                          | Setup                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------ |
| **Network administrator**         | **Admin**, or a custom role with LoRaWAN Menu + Read + Write + Delete          |
| **Device installer**              | Custom role: Assets and LoRaWAN Menu + Read + Write, no Delete                 |
| **Read-only network monitor**     | Custom role: LoRaWAN Menu + Read only                                          |
| **Dashboard viewer**              | **Viewer** (no LoRaWAN or Events)                                              |
| **Regional gateway manager**      | LoRaWAN Menu + Read + Write, plus entity restrictions on the site's gateway(s) |
| **Action editor without LoRaWAN** | Actions Menu + Read + Write, LoRaWAN menu off                                  |
| **Contractor for one site**       | Assets Menu + Read (+ Write), entity restrictions on that site's devices       |

***

## Limitations & best practices

**Limitations**

* System roles cannot be customized.
* Billing and subscription management are reserved for administrators.
* Users can only grant permissions they hold themselves.
* Entity restrictions are an allow-list: once any restriction exists for a type, every other entity of that type is denied.
* A role with entity restrictions cannot create new entities of the restricted type.

**Best practices**

1. **Least privilege**: grant only what each user needs.
2. **Prefer custom roles** to giving everyone Admin.
3. **Use entity restrictions** for contractors and site-specific operators.
4. **Keep Can delete off** unless the user really needs to remove resources.
5. **Fill in the Description**, so others know who the role is for.
6. **Review roles regularly** and downgrade access when people change jobs or leave.
7. **Separate LoRaWAN from data access**: not everyone who views dashboards needs network server rights.

***

## Quick checklist

**Creating a custom role**

* [ ] Name and description set
* [ ] Menu toggles on for every section the user needs
* [ ] Read / Write / Delete match the intended actions
* [ ] Entity restrictions added (if needed)
* [ ] Users / Manage roles granted only when required
* [ ] Role tested with a non-admin account before wide rollout

**Granting LoRaWAN access**

* [ ] LoRaWAN **Menu** on
* [ ] **Read** for viewing, **Write** for adding and editing, **Delete** for removing
* [ ] Entity restrictions on gateways / profiles / devices (if needed)
* [ ] Role assigned to the user on the Overview page
