Role-Based Access Control

A Role in ThingsBoard PE defines a set of permissions — which resources a user can access and which operations they can perform. Roles are never assigned directly to users; they flow through three building blocks:

Object	What it is
Role	Defines what is allowed: resource type + operations
User Group	Defines who receives the permissions
Group Permission Entity (GPE)	The link between a User Group and a Role — ThingsBoard creates it automatically when you assign a role to a user group

Users do not receive permissions directly. Instead:

Depending on the role type:

• Generic role — applies recursively to all entities within a Tenant or Customer scope.
• Group role — applies strictly to a specific Entity Group.

Access is denied by default. A user can only do what an explicitly assigned role permits. There are no deny rules — permissions are purely additive. If a user belongs to multiple user groups, all permissions are combined.

Authority defines a user’s position in the system hierarchy and determines the maximum capabilities available to that user.

The platform supports three authority levels:

Authority level	Description
SYS_ADMIN	Assigned to System Administrator users
TENANT_ADMIN	Assigned to users on the Tenant level
CUSTOMER_USER	Assigned to users on the Customer level

• A user’s authority level is determined at creation time based on where in the hierarchy the user is created.
• This authority level can be changed by changing Customer level on the Tenant’s one and vice versa.
• You cannot change the authority level for the sysadmin user and neither tenant nor customer user can be elevated to the level of SYS_ADMIN authority.

ThingsBoard PE supports two role types:

Role type	Scope model	Use case
Generic	Recursive within Tenant/Customer scope	Broad administrative access
Group	Specific entity group only	Segmented and isolated access

A Generic role defines a set of permissions that applies recursively to all entities within a selected scope: Tenant, Customer, or Sub-customer (including all descendants).

The scope is not a property of the role itself — it is determined by where the role is assigned. The same role assigned to a user group at Tenant level grants tenant-wide access; assigned at Customer level it grants access only within that customer and its sub-customers.

A Generic role is assigned to a user group via a Group Permission Entity (GPE), which records the user group, the role, and the scope level.

Key characteristics

• Scope depends on the assignment level (Tenant or Customer).
• Does not require entity groups.
• Applies to all entities within the defined scope.
• Supports hierarchical customer structures.

1. Navigate to Security ⇾ Roles.
2. Click + Add role.
3. Fill in the Name — unique role name
4. Role type — select Generic
5. Configure Permissions: Resource and Operations
   (At least one permission entry must be specified).
6. Click Add.

You can find a description of all available resource types in the permissions table.

To apply a Generic role:

1. Open Users ⇾ Groups (Tenant level)
   or
   Open Customers ⇾ Manage customer users ⇾ Groups (Customer level).
2. Open group details.
3. Navigate to Roles tab.
4. Click Add.
5. Select:
   • Role type: Generic
   • Choose the created role
6. Click Add.

The role now applies recursively within the group’s scope.

A Group role defines permissions for a specific user group over a specific entity group.

Unlike Generic roles, which apply recursively within a scope, Group roles restrict access strictly to explicitly selected entity groups.

Assignment is implemented via a Group Permission Entity (GPE) that links:

• User Group
• Entity Group
• Group Role (permissions)

This model enables precise, group-level access control without extending permissions beyond the targeted entities.

Key characteristics

• Requires an entity group.
• Applies only to selected entities.
• Enables strong segmentation and isolation.
• Suitable for controlled access within the same tenant.

Every entity group list (Devices, Dashboards, Assets, etc.) has a Share icon on each row that opens a one-step sharing dialog — no separate role creation needed for common permission levels:

1. Navigate to the entity group list (e.g., Dashboards ⇾ Groups).
2. Click the Share icon on the desired group row.
3. Select the Customer to share with.
4. Either enable All users or select a specific user group within that customer.
5. Select the Permission level:
   • Read — read-only access (no pre-created role required)
   • Write — read and write access (no pre-created role required)
   • Other — select one or more named Group roles you have already created
6. Click Share.

ThingsBoard creates the GPE automatically. The shared group becomes visible to the selected users with the specified permission level.

Approach	When to use
Quick share (Read / Write)	Sharing a group in one step with no pre-created role
Quick share (Other)	Applying a named Group role via the share dialog
Full role assignment (via Permissions tab)	Reusable roles shared across multiple groups or complex multi-group setups

1. Navigate to Security ⇾ Roles.
2. Click + Add role.
3. Fill in the Name — unique role name
4. Role type — select Group
5. Under Permissions, specify required operations. (At least one permission entry must be specified).
6. Click Add.

The Group role is now available for assignment to entity groups.

1. Navigate to the relevant entity type (e.g., Devices ⇾ Groups).
2. Open the target entity group details.
3. Go to the Permissions tab.
4. Click Add.
5. Select:
   • The created Group role
   • Owner
   • Target user group
6. Click Add.

The role now applies only to that entity group.

ThingsBoard automatically creates two user groups with associated Generic roles when a Tenant or Customer is created. These defaults give you a working permission structure out of the box.

User group	Associated role	Default permissions
Tenant Administrators	Tenant Administrator (Generic)	All resources — All operations
Tenant Users	Tenant User (Generic)	Profile — All operations; All resources — Read, RPC Call, Read Credentials, Read Attributes, Read Telemetry, Read Calculated Field and Alarm Rules

User group	Associated role	Default permissions
Customer Administrators	Customer Administrator (Generic)	All resources — All operations
Customer Users	Customer User (Generic)	Profile — All operations; All resources — Read, RPC Call, Read Credentials, Read Attributes, Read Telemetry

You can modify these default roles or use them as a starting point when building custom permission structures.

---

Recipe	Role types	What it demonstrates
Read-only analyst	Generic	Read-only access to all tenant entities and telemetry
Customer scoped access	Generic	Restrict users to their own customer’s data without entity groups
Generic role scope	Generic	How the same role grants different access at Tenant vs. Customer level
Isolated device groups	Group	Per-group device access with no cross-access between user groups
Multi-facility access control	Generic + Group	Supervisors, facility managers, and end users across multiple buildings

Each permission entry in a role specifies a resource type and one or more operations:

Operation	What it allows
Read	View entity details, configuration, and settings
Write	Modify entity details, attributes, and configuration
Create	Create new entities of this resource type
Delete	Delete entities of this resource type
RPC Call	Send RPC commands to devices
Read Attributes	Read entity attributes (client, shared, and server-side)
Read Telemetry	Read entity time-series telemetry data
Claim Devices	Claim unowned devices under the current tenant or customer
All	All of the above

Permissions are evaluated per resource type — you can grant Read on Device and Write on Dashboard as separate entries within the same role.

---

The table below lists all available resource types that can be secured using RBAC in ThingsBoard Professional Edition.

Each resource represents a platform entity or system component that supports permission-based access control. Permissions are configured within roles and determine what operations users are allowed to perform on these resources.

Resource	Description
All	Grants selected operations across all resources within the assigned scope.
API Usage State	Access API usage statistics and telemetry metrics.
Alarm	View and manage platform alarms.
Asset	Manage logical IoT entities such as facilities, vehicles, or fields.
Asset Group	Manage groups of assets for structured access control.
Asset Profile	Configure shared settings for multiple assets.
Audit Log	View system activity and user action history.
Billing	Manage billing information and payment configuration.
Blob Entity	Manage stored binary objects used for reporting and dashboard snapshots.
Converter	Manage uplink and downlink data converters in integrations.
Customer	Manage customer entities within the tenant hierarchy.
Customer Group	Manage logical groupings of customers.
Dashboard	Create and manage dashboards and visualizations.
Dashboard Group	Manage dashboard collections.
Device	Manage IoT devices, telemetry, attributes, credentials, and RPC interactions.
Device Group	Manage groups of devices for structured segmentation.
Device Profile	Configure shared device behavior and settings.
Edge	Manage ThingsBoard Edge instances.
Edge Group	Manage groups of Edge instances.
Entity View	Provide limited exposure of device or asset data to customers.
Entity View Group	Manage grouped entity views.
Group Permission	Manage RBAC mappings between user groups, roles, and entity groups.
Integration	Manage external system integrations.
Notification	Manage platform notifications and delivery channels.
OTA Package	Manage firmware and software update packages for devices.
Profile	Manage personal user profile settings.
Queue	Manage rule engine processing queues.
Resource	Manage shared resource library files.
Role	Manage RBAC roles and permission definitions.
Rule Chain	Configure data processing and automation logic.
Scheduler Event	Manage scheduled automation events.
Tenant	Manage tenant-level configuration and hierarchy.
User	Manage user accounts and access settings.
User Group	Manage user groups for RBAC assignments.
Version Control	Export and restore ThingsBoard entities using Git-based version control.
White Labeling	Configure platform branding and UI customization.
Widget Type and Widget Bundle	Manage widget definitions and widget bundles in the UI library.