Roles

Public surface of the Roles service.

A role bundles permissions (actions) and is granted to a principal — a user, a group, or an external application — through a role assignment. Together with users and groups this completes role-based access control (RBAC): put users in groups, grant roles to the groups, then ask what a principal can do. Built-in roles are read-only; custom roles can be created, changed, and deleted.

Usage¶

Prerequisites: Initialize the SDK first - see Getting Started

import { Roles } from '@uipath/uipath-typescript/roles';

const roles = new Roles(sdk);
const allRoles = await roles.getAll();

Methods¶

create()¶

create(request: PlatformRoleCreateRequest): Promise<PlatformRoleGetResponse>

Creates a custom role.

Actions are referenced by their fully qualified names — pick them from getActions(). The name must be unique in the organization.

Parameters¶

Parameter	Type	Description
`request`	`PlatformRoleCreateRequest`	The role to create

Returns¶

Promise<PlatformRoleGetResponse>

The created role as stored, as a PlatformRoleGetResponse

Example¶

import { PlatformRoleScopeType } from '@uipath/uipath-typescript/roles';

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

const role = await roles.create({
  name: 'Ticket Auditor',
  scopeType: PlatformRoleScopeType.Organization,
  description: 'Read-only access for ticket audits',
  actionsGrantedByRole: [actions[0].name],
});

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.

The first row is the header; each following row is one assignment (role and principal). Group-inherited access is not expanded — use getEffectiveAccess() for a single principal's full picture.

Returns¶

Promise<string>

The CSV document as a string

Example¶

const csv = await roles.exportAssignments();

getActions()¶

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

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

Use it to pick the actionsGrantedByRole names when creating or updating a custom role.

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' });

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, sorting, 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, sorting, 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/roles';

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

const roles = new Roles(sdk);
const allRoles = await roles.getAll();

import { PlatformRoleType, PlatformRoleSortField, PlatformRoleSortOrder } from '@uipath/uipath-typescript/roles';

const customRoles = await roles.getAll({
  roleType: PlatformRoleType.Custom,
  contains: 'Ticket',
  sortBy: PlatformRoleSortField.Name,
  sortOrder: PlatformRoleSortOrder.Ascending,
  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.

Each item is one principal (user, group, or application) with every role assigned to it at the given scope. Assignments carry their own GUID, which is what updateAssignments() uses to revoke them. pageSize may not exceed 100.

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('/');

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¶

// Get a role id from the listing first
const allRoles = await roles.getAll();

const role = await roles.getById(allRoles.items[0].id);

getEffectiveAccess()¶

getEffectiveAccess(tenantId: string, principal: PlatformEffectiveAccessPrincipal): Promise<PlatformEffectiveAccessResponse>

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

This answers "what can this principal do here": the response lists every effective role together with the assignments granting it, plus metadata for the granted services and roles.

Parameters¶

Parameter	Type	Description
`tenantId`	`string`	GUID of the tenant to compute access in
`principal`	`PlatformEffectiveAccessPrincipal`	The user or group to check

Returns¶

Promise<PlatformEffectiveAccessResponse>

The principal's effective access, as a PlatformEffectiveAccessResponse

Examples¶

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

const access = await roles.getEffectiveAccess('<tenantId>', { groupId: '<groupId>' });

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 from the Users or Groups service (users.getAll() / groups.getAll()).

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/roles';

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

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

updateById()¶

updateById(roleId: string, update: PlatformRoleUpdateOptions): Promise<PlatformRoleGetResponse>

Updates a custom role.

Only the fields present in update are changed — omitted fields keep their current values, including the granted actions. Passing actionsGrantedByRole replaces the full set. Built-in roles cannot be updated.

Parameters¶

Parameter	Type	Description
`roleId`	`string`	GUID of the role to update
`update`	`PlatformRoleUpdateOptions`	The fields to change

Returns¶

Promise<PlatformRoleGetResponse>

The role as stored after the update, as a PlatformRoleGetResponse

Examples¶

const updated = await roles.updateById('<roleId>', { name: 'Ticket Managers' });

const role = await roles.getById('<roleId>');
await roles.updateById(role.id, {
  actionsGrantedByRole: [...role.actionDetails.map(a => a.name), 'AUTHZ.ROLE.READ'],
});