Roles

Public surface of the platform Roles service. JSDoc on this interface drives the generated API reference documentation.

Roles bundle permissions (actions) and are granted to principals — users, groups, external applications — through role assignments. Together with users and groups this completes the RBAC model: put users in groups, grant roles to the groups, and ask getEffectiveAccess() what a principal can do.

Methods

deleteById()

deleteById(roleId: string): Promise<void>

Deletes a custom role. Built-in roles cannot be deleted.

Parameters

Parameter	Type	Description
roleId	string	GUID of the role to delete

Returns

Promise<void>

Resolves when the role has been deleted

Example

await roles.deleteById('<roleId>');

---

exportAssignments()

exportAssignments(): Promise<string>

Exports all direct role assignments of the organization as CSV.

Returns

Promise<string>

The CSV document as a string

Example

const csv = await roles.exportAssignments();
console.log(csv.split('\n')[0]); // header row

---

getActions()

getActions(options?: PlatformRoleActionGetAllOptions): Promise<PlatformRoleAction[]>

Gets the catalog of permission (action) definitions roles can grant, optionally filtered by owning service or scope level.

Use it to pick the actionsGrantedByRole names when creating a custom role with upsert().

Parameters

Parameter	Type	Description
options?	PlatformRoleActionGetAllOptions	Filtering options

Returns

Promise<PlatformRoleAction[]>

The action definitions, as PlatformRoleAction items

Example

const actions = await roles.getActions({ serviceName: 'AuthZ' });
for (const action of actions) {
  console.log(`${action.name}: ${action.description}`);
}

---

getAll()

getAll<T>(options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<PlatformRoleGetResponse> : NonPaginatedResponse<PlatformRoleGetResponse>>

Gets the organization's roles, built-ins included, with optional filtering and pagination.

Each role carries the permissions it grants (actionDetails).

Type Parameters

Type Parameter	Default type
T extends PlatformRoleGetAllOptions	PlatformRoleGetAllOptions

Parameters

Parameter	Type	Description
options?	T	Filtering and pagination options

Returns

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<PlatformRoleGetResponse> : NonPaginatedResponse<PlatformRoleGetResponse>>

All roles when no pagination options are given, one page otherwise, as PlatformRoleGetResponse items

Examples

import { UiPath } from '@uipath/uipath-typescript/core';
import { Roles } from '@uipath/uipath-typescript/platform';

const sdk = new UiPath(config);
await sdk.initialize();

const roles = new Roles(sdk);
const allRoles = await roles.getAll();
for (const role of allRoles.items) {
  console.log(`${role.name} (${role.type}) — ${role.actionDetails.length} permissions`);
}

import { PlatformRoleType } from '@uipath/uipath-typescript/platform';

const customRoles = await roles.getAll({
  roleType: PlatformRoleType.Custom,
  contains: 'Ticket',
  pageSize: 20,
});

---

getAssignments()

getAssignments<T>(scope: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<PlatformPrincipalRoleAssignments> : NonPaginatedResponse<PlatformPrincipalRoleAssignments>>

Gets the organization's role assignments grouped by principal, with optional filtering and pagination.

Type Parameters

Type Parameter	Default type
T extends PlatformRoleAssignmentGetAllOptions	PlatformRoleAssignmentGetAllOptions

Parameters

Parameter	Type	Description
scope	string	The scope to list assignments for; / means the whole organization
options?	T	Filtering and pagination options

Returns

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<PlatformPrincipalRoleAssignments> : NonPaginatedResponse<PlatformPrincipalRoleAssignments>>

All assignment groups when no pagination options are given, one page otherwise, as PlatformPrincipalRoleAssignments items

Examples

const assignments = await roles.getAssignments('/');
for (const principal of assignments.items) {
  console.log(`${principal.displayName}: ${principal.roleAssignments.map(a => a.roleName)}`);
}

const assignments = await roles.getAssignments('/', {
  securityPrincipalId: '<userId>',
});

---

getById()

getById(roleId: string): Promise<PlatformRoleGetResponse>

Gets a role by ID, built-ins included.

Parameters

Parameter	Type	Description
roleId	string	GUID of the role

Returns

Promise<PlatformRoleGetResponse>

The role with its permissions, as a PlatformRoleGetResponse

Example

const role = await roles.getById('<roleId>');
console.log(role.actionDetails.map(a => a.name));

---

getEffectiveAccess()

getEffectiveAccess(request: PlatformEffectiveAccessRequest): Promise<PlatformEffectiveAccessResponse>

Computes the roles a principal effectively holds in a tenant — directly and through group membership.

This is the RBAC question "what can this user do here": the response groups every effective role with the assignments granting it, plus metadata for the granted services and roles.

Parameters

Parameter	Type	Description
request	PlatformEffectiveAccessRequest	The principal and tenant scope to compute access for

Returns

Promise<PlatformEffectiveAccessResponse>

The principal's effective access, as a PlatformEffectiveAccessResponse

Example

const access = await roles.getEffectiveAccess({
  tenantId: '<tenantId>',
  userId: '<userId>',
});
const isAdmin = access.roles.some(r => r.roleName === 'Administrator');

---

updateAssignments()

updateAssignments(changes: PlatformRoleAssignmentChanges): Promise<void>

Adds and removes role assignments atomically.

Additions grant a role to a principal; removals are identified by assignment GUID (from getAssignments()). If a removal fails, added assignments are rolled back on a best-effort basis.

First, get role IDs with getAll() and principal IDs with users.getAll() or groups.getAll() (from @uipath/uipath-typescript/platform).

Parameters

Parameter	Type	Description
changes	PlatformRoleAssignmentChanges	The assignments to add and remove

Returns

Promise<void>

Resolves when the changes have been applied

Examples

import { PlatformPrincipalType } from '@uipath/uipath-typescript/platform';

await roles.updateAssignments({
  toAdd: [{
    roleId: '<roleId>',
    securityPrincipalId: '<groupId>',
    securityPrincipalType: PlatformPrincipalType.Group,
    scope: '/',
  }],
});

await roles.updateAssignments({ toDelete: ['<roleAssignmentId>'] });

---

upsert()

upsert(request: PlatformRoleUpsertRequest): Promise<PlatformRoleGetResponse>

Creates or updates a custom role.

Omit request.id to create a new role; pass it to overwrite an existing custom role. Built-in roles cannot be changed. Actions are referenced by their fully qualified names — pick them from getActions().

Parameters

Parameter	Type	Description
request	PlatformRoleUpsertRequest	The role to create or update

Returns

Promise<PlatformRoleGetResponse>

The role as stored after the write, as a PlatformRoleGetResponse

Example

const actions = await roles.getActions({ serviceName: 'AuthZ' });

const role = await roles.upsert({
  roleName: 'Ticket Auditor',
  roleScopeType: 'ORGANIZATION',
  organizationId: '<organizationId>',
  roleDescription: 'Read-only access for ticket audits',
  actionsGrantedByRole: [actions[0].name],
});