Role-Based Access Control (RBAC)

Updated 02/09/26

If you are beta testing this feature, please report any bugs or issues you find

Review API breaking changes

Overview

ImmyBot’s RBAC system provides granular permission management, allowing you to control exactly what users can access and modify within your environment. This system has been designed with a phased approach to ensure seamless migration from legacy permissions while introducing powerful new capabilities.

1. Roles
2. Groups
3. Role Assignments
4. Users
5. Profile
6. Object Authorization

Roles

A role grants one or more capabilities. There are 100+ capabilities to choose from. Some examples are ‘Manage Software’ and ‘Manage Billing’.

Built-In Roles

In an effort to provide a seamless transition for existing customers, four built-in legacy roles have been added that mirror existing permission structures:

Role	Description	Legacy User Type
System Administrator (Legacy)	Grants every permission available	MSP Admin
System User (Legacy)	Same as system admin but with a few restrictions	MSP Non-Admin
Administrator (Legacy)	Broad access with no system permissions	Tenant Admin
User (Legacy)	Limited access	Tenant Non-Admin

Additional built-in roles have been added to maintain compatibility with existing user settings and application preferences.

Role	Description	Legacy preference
Script Manager	Permission to manage scripts	Used in favor of the ‘Allow Non-Admins and Non-MSP Users to Use Terminal and Edit Scripts’ application preference
Computer Terminal User	Grants access to run scripts against a computer in the terminal tab	Used in favor of the ‘Allow Non-Admins and Non-MSP Users to Use Terminal and Edit Scripts’ application preference
Deployment Manager	Permission to manage deployments	Used in favor of the ‘Allow Non-Admin Users to Manage Deployments’ application preference
Cross-Tenant Deployment Manager	Permission to manage cross-tenant deployments	Used in favor of the user checkox ‘Can Manage Cross Tenant Deployments’.
Cross-Tenant Deployment Change Requester	Permission to manage cross-tenant deployments through change requests	Used in favor of the the ‘Require Change Requests for Non-Admin Cross-Tenant Deployments’ application preference.

Built-in roles are inherently available to all tenants. However, in order to assign a role that contains system permissions, a user must be granted the Assign Cross-Tenant Roles permission. Built-in roles are read-only and the permissions they grant cannot be modified.

Custom Roles

You are encouraged to create your own custom roles to suite your needs.

If you have the Manage Public Roles permission, then you can create a role that any user in the system can see.

Otherwise, a role is owned by a specific tenant. A user can only see public roles or roles that are managed by a tenant they have permission to manage roles for.

Role Capabilities

There are 100+ different permissions that can be granted for a given role.

System permissions

Many permissions can be scoped to a particular set of tenants or resources through role assignments. Other permissions, such as ‘Manage Billing’ are denoted as system permissions and cannot be limited to certain tenants. System permissions are traditionally reserved for MSP users and should be carefully considered when granted to non-MSP users.

Groups

A group is a collection of users that share the same permission requirements. Since, managing permissions for individual users can be very tedious, we encourage the adoption of groups.

A group can be granted one or more role assignments.

Members of a group inherit all role assignments assigned to the group.

If a group is owned by a specific tenant, then only users that belong to that tenant can be added to the group.

Role Assignments

Permissions are granted or denied to users through Role Assignments. Role assignments can be assigned to Groups or directly to users.

An assignment contains a selected role, a selected scope, and an “Allow” or “Deny” value. Users can have multiple role assignments where they are allowed the cumulative allowed permissions from allow role assignments. Denied role assignments take precedence when determining if a user has access to a particular permission or resource.

Role Assignment Scopes

Scope	Description
Owner	Scopes the role at the highest level where you have full access to all tenants in the system.
MSP	Scopes the role to the MSP tenant and all tenants that belong to the MSP.
Specific Tenant	Scopes the role to the selected tenant.
Tenant Tag	Scopes the role to all tenants with the selected tag.
User’s Tenant	Scopes the role only to the tenant of the selected user. Useful for giving your customers access to their own tenant.
Resource	Grants the role at the selected resource scope. The only resource type supported for now is Computers.

Users

A user is a person who has been granted access to ImmyBot.

Creating a user

1. Access Requests – Users can request access and will show up on the main Users & Roles page.
2. From Existing People – Existing people can be promoted to a user. If you can’t find a specific person, you may need to link their azure customer to a tenant in ImmyBot.
3. Manually – You can always manually create a user if you know their Azure Object ID.

View all direct role assignments

On the main Users & Roles page, we have a tab to view all direct role assignments. For existing customers, you will see that all of your users have been migrated over to direct role assignments. Consider replacing these direct role assignments with groups to better organize your users.

My User’s Group and Role Assignments

You can now view your own user’s group and role assignments on the profile page. The profile page can be accessed at /profile or by clicking the profile link in your account dropdown located in the top-right of the page.

Profile

A profile page has been added at /profile where you can easily view your own permissions.

Object Authorization

Scripts, Software, Tasks, Tags, and Media have authorization sections.

A user’s permissions under RBAC will be taken into account when determining whether a user is allowed to view or manage one of these objects.

Api Breaking Changes

Latest API Documentation

The central theme of this release is the full migration from the old tenant-relationship authorization model to the new RBAC system with granular user-role-assignments.

---

1. Removed Endpoints (UsersController)

Removed Route	Old Action	Replacement
POST /api/v1/users/create-from-person	CreateFromPerson	POST /api/v1/users/bulk-create
POST /api/v1/users/grant-access	GrantAccessRbac	New UserRoleAssignmentsController
POST /api/v1/users/add-roles	BulkAssignRolesToPeople	New UserRoleAssignmentsController
POST /api/v1/users/remove-roles	BulkRemoveRolesFromPeople	New UserRoleAssignmentsController

POST /api/v1/users/bulk-create (replaces create-from-person)

Old request body (CreateUserFromPersonRequest):
{
  "personId": int,
  "hasManagementAccess": bool
}

New request body (CreateUserFromPersonRequest):
{
  "personIds": [int],        // min 1 required
  "expirationTime": string
}

• Single PersonId → List<int> PersonIds
• HasManagementAccess removed, ExpirationTime added
• Return type changed from GetUserResponse to CreateUsersFromPersonIdsResponse

PUT /api/v1/users/{userId} (UpdateUserPayload changed)

Old: { id, isAdmin, tenantId, canManageCrossTenantDeployments, hasManagementAccess }
New: { id, isAdmin, tenantId, canManageCrossTenantDeployments }

HasManagementAccess removed.

GrantAccessRequest simplified

Old: { isAdmin, hasManagementAccess, expirationTime }
New: { expirationTime }

---

2. GetUserResponse Changes

Removed properties

• bool HasManagementAccess
• List<string> Roles

Added properties

• int GroupCount
• List<string> Groups
• int DirectRoleCount

---

3. GetAuthDetailsResponse Changes

Removed from DTO

• bool HasManagementAccess

No longer populated by controller (properties still exist on DTO but always default)

• IsAdmin
• IsSupportTechnician
• CanManageCrossTenantDeployments
• IsImmense

Behavior changes

• BackendRegAppId — was only set for MSP admins, now unconditionally set
• OpenAccessRequestCount — was gated on isMspAdmin, now gated on IUsersManageAccessRequestsPermission

New auth endpoints

• GET /api/v1/auth/me/permissions/{permissionType}/tenants
• GET /api/v1/me/permissions

---

4. Tenant Relationships → Authorized Viewers

Applies to all resource models: Software, Scripts, Maintenance Tasks, Media, and Tags.

Removed from all resource models

• ICollection<TenantXxx> TenantRelationships
• bool Owned

Added to all resource models

• ICollection<XxxViewer> AuthorizedViewers
• bool VisibleToAllTenants
• int TenantId (owner tenant)
• Tenant? OwnerTenant

New /authorization sub-endpoints

These replace per-entity tenant relationship management.

Controller	GET	POST
Scripts	/api/v1/scripts/local/{id}/authorization	/api/v1/scripts/local/{id}/authorization
Software	/api/v1/software/local/{id}/authorization	/api/v1/software/local/{id}/authorization
MaintenanceTasks	/api/v1/maintenance-tasks/{id}/authorization	/api/v1/maintenance-tasks/{id}/authorization
Media	/api/v1/media/local/{id}/authorization	/api/v1/media/local/{id}/authorization
Tags	/api/v1/tags/{id}/authorization	/api/v1/tags/{id}/authorization

---

5. ScriptType → DatabaseType

On IScriptDetailsBase and all implementing DTOs, the property ScriptType was renamed to DatabaseType.

---

6. Permission Type Renames

Roles permissions

Old	New
IRbacSubject	IRolesSubject
IRbacSubjectPermission	IRolesSubjectPermission
IRbacViewPermission	IRolesViewPermission
IRbacManagePermission	IRolesManagePermission

New permission added: IRolesManageApplicationLevelPermissionsPermission

ChangeRequests permissions (split from one into three)

Old	New
IChangeRequestManagePermission	IDeploymentsManageChangeRequestsPermission
	IDeploymentsViewChangeRequestsPermission
	IDeploymentsApproveChangeRequestsPermission

ChangeRequestsController endpoint permission mapping

Endpoints	Old Permission	New Permission
DELETE /api/v1/change-requests/{id}	IChangeRequestManagePermission	IDeploymentsManageChangeRequestsPermission
POST .../approve, .../deny, .../require-changes	IChangeRequestManagePermission	IDeploymentsApproveChangeRequestsPermission
POST .../comment, GET .../dx, GET .../open-count	IChangeRequestManagePermission	IDeploymentsViewChangeRequestsPermission

RolesController GetPermissions authorization change

GetPermissions changed from IRbacViewPermission to INoAuthorizationPermission (accessible to all authenticated users).

IPermissionMetadata simplified

Removed properties:

• string Claim
• string DenyClaim
• string SubjectClaimType
• string TenantClaimType
• string ResourceClaimType

Added: string SubjectPermissionClaimType

Retained: string AllowClaim (backwards compatibility with frontend)

IRoleClaimMetadataService

Deleted entirely, along with RoleClaimParseException.

---

7. New Controllers

GroupsController — /api/v1/groups

Method	Route	Action
GET	/api/v1/groups	GetAll
GET	/api/v1/groups/{groupId}	Get
POST	/api/v1/groups	Create
PUT	/api/v1/groups/{groupId}	Update
DELETE	/api/v1/groups/{groupId}	Delete
GET	/api/v1/groups/{groupId}/role-assignments	GetRoleAssignments
POST	/api/v1/groups/{groupId}/members	AddUserToGroup
POST	/api/v1/groups/{groupId}/members/bulk	AddUsersToGroup
DELETE	/api/v1/groups/{groupId}/members/{userId}	RemoveUserFromGroup
GET	/api/v1/groups/{groupId}/members	GetGroupMembers

UserRoleAssignmentsController — /api/v1/user-role-assignments

Method	Route	Action
GET	/api/v1/user-role-assignments	DxGetAll
GET	/api/v1/user-role-assignments/users/{userId}	DxGetByUserId
GET	/api/v1/user-role-assignments/users/{userId}/count	GetUserRoleAssignmentsCount
POST	/api/v1/user-role-assignments/owner/create	CreateOwnerAssignments
POST	/api/v1/user-role-assignments/msp/create	CreateMspAssignments
POST	/api/v1/user-role-assignments/tenant-tag/create	CreateTenantTagAssignments
POST	/api/v1/user-role-assignments/specific-tenant/create	CreateSpecificTenantAssignments
POST	/api/v1/user-role-assignments/user-tenant/create	CreateUserTenantAssignments
POST	/api/v1/user-role-assignments/tag-resource/create	CreateTagResourceAssignments
POST	/api/v1/user-role-assignments/specific-resource/create	CreateSpecificResourceAssignments
POST	/api/v1/user-role-assignments/category-resource/create	CreateCategoryResourceAssignments
DELETE	/api/v1/user-role-assignments/delete	DeleteUserRoleAssignments

EffectivePermissionsController — /api/v1/effective-permissions

Method	Route	Action
POST	/api/v1/effective-permissions/users/{userId}/evaluate/all-assignments	EvaluateAllAssignments
POST	/api/v1/effective-permissions/users/{userId}/evaluate/tenant	EvaluateForTenant
POST	/api/v1/effective-permissions/users/{userId}/evaluate/resource	EvaluateForResource
POST	/api/v1/effective-permissions/groups/{groupId}/evaluate/all-assignments	EvaluateAllAssignmentsForGroup
POST	/api/v1/effective-permissions/groups/{groupId}/evaluate/tenant	EvaluateForTenantForGroup
POST	/api/v1/effective-permissions/groups/{groupId}/evaluate/resource	EvaluateForResourceForGroup

New endpoint on UsersController

Method	Route	Action
GET	/api/v1/users/{userId}/groups	GetUserGroups

New endpoint on MaintenanceTasksController

Method	Route	Action
GET	/api/v1/maintenance-tasks/tenant-management	GetTenantManagement

New endpoint on RolesController

Method	Route	Action
GET	/api/v1/roles/{roleId}/assignments	GetRoleAssignments

---

8. Roles & ChangeRequests Model Changes

CreateOrUpdateRoleRequest

Added required property:

int OwnerTenantId  // required

GetRoleResponse

Added properties:

int? OwnerTenantId
string OwnerTenantName

IChangeRequestStore

Both CreateChangeRequestForNewEntity and CreateChangeRequestForExistingEntity now require an additional int ownerTenantId parameter.