uip admin authorization

Syntax and options for `uip admin authorization`, which manages Authorization-service roles, role assignments, the permissions catalog, and effective-access lookups.

uip admin authorization manages UiPath Authorization-service primitives: custom role definitions on the Policy Administration Point (PAP), who has which role (role assignments), a read-only catalog of permission definitions, and effective-access lookups against the Policy Decision Point (PDP). It ships as the @uipath/authz-commands package, one of seven sub-packages assembled into the single uip admin tool — see uip admin for the full directory of admin sub-resources.

Note:

Role/permission policy CRUD for built-in product areas lives on a different command — uip gov access-policy — which targets the same authz-sdk swagger but is owned by the governance tool. This page is about custom roles, who's assigned them, and computing effective access.

This resource spans one page

Every verb below is invoked as uip admin authorization <verb> — there is no separate sibling page for this sub-resource.

Concepts

• Role shape — a role's --scope plus optional --service together determine where it applies: Organization (org-wide), TenantGlobal (a template applied across every tenant), Tenant (one tenant), or Project (scoped to a service that registers Project-level permissions, e.g. Document Understanding, Reinfer). --service alone infers the scope from the service registry — an org-level service (e.g. apps) infers Organization; a tenant-level service (e.g. documentunderstanding) infers Tenant. Combine --scope and --service to override the inference.
• Authoring is blocked for services that own their own role catalog — orchestrator, dataservice, insights, taskmining, testmanager, automationops, casemanagement, processmining — and for platform-level services — authz, oms, platform, identity, licensing. roles create/update/delete and roles assignments create all reject --service values from this list; listing roles/permissions/assignments for these services still works.
• Role authoring is a PUT-style upsert — roles create always creates a new role (the id is server-generated); roles update <id> re-sends the full role body with the same id. update without --description preserves the current description by fetching the role first — it does not clear it.
• Assignment scope composition — roles assignments list/create build a scope path from --scope/--service/--scope-id/--tenant-id using the same inference matrix as role authoring, with an escape hatch: --scope-path <path> sends an exact path verbatim, overriding every other scope flag. TenantGlobal is not a valid assignment scope (only a role-authoring scope) except as a create-time alias for Tenant.
• Batch mode — roles assignments create --file <path> and roles assignments delete --file <path>/<id> accept JSON arrays for bulk operations, mutually exclusive with the inline single-item flags/argument. The underlying bulk-update endpoint is best-effort atomic and silently no-ops on unknown/already-deleted assignment ids — delete does not verify ids existed beforehand.
• --login-validity <minutes> is available on every verb here (overrides the interactive-login token lifetime for that one call — rarely needed).

Synopsis

uip admin authorization roles list [--limit <n>] [--offset <n>] [--filter <fragment>] [--service <service>] [--scope <type>] [--role-type BuiltIn|Custom] [--tenant-id <guid>]
uip admin authorization roles get <id>
uip admin authorization roles create --name <name> --file <path> [--description <text>] [--service <service>] [--scope <type>] [--tenant-id <guid>]
uip admin authorization roles update <id> --name <name> --file <path> [--description <text>] [--service <service>] [--scope <type>] [--tenant-id <guid>]
uip admin authorization roles delete <id>

uip admin authorization roles assignments list [--limit <n>] [--offset <n>] [--service <service>] [--identity-id <id>] [--scope <type>] [--scope-id <id>] [--scope-path <path>] [--tenant-id <guid>] [--include-inherited]
uip admin authorization roles assignments create (--role-id <guid> --identity-id <guid> --identity-type <type> [--service <service>] [--scope <type>] [--scope-id <id>] [--scope-path <path>] [--tenant-id <guid>]) | --file <path>
uip admin authorization roles assignments delete [<id>] | --file <path>

uip admin authorization permissions list [--service <service>] [--scope <type>]

uip admin authorization check-access [<identity>] [--scope Tenant|Folder] [--tenant-id <guid>] [--folder-id <guid>] [--service <service>] | --file <path>

uip admin authorization roles

Manage custom role definitions on the PAP.

uip admin authorization roles list

List roles for the caller's organization — both built-in and custom by default.

Options

Long	Value	Default	Description
--limit <n>	integer	20	Page size.
--offset <n>	integer	0	Records to skip (zero-based).
--filter <fragment>	string	—	Substring match on role name.
--service <service>	string	—	Owning service (e.g. apps, documentunderstanding). Combines with --scope, or alone infers the scope from the service registry.
--scope <type>	Organization|TenantGlobal|Tenant|Project|Folder	—	Filter by role shape. Optional when --service is given.
--role-type <type>	BuiltIn|Custom	—	Filter by role type.
--tenant-id <guid>	UUID	—	Restrict to roles scoped to a specific tenant. Look up a UUID with uip admin tenants list --filter <name>.

Listing works for every service, including ones whose role catalog can't be authored via this CLI (see Concepts) — only authoring is blocked.

Examples

uip admin authorization roles list
uip admin authorization roles list --scope Organization
uip admin authorization roles list --service apps --filter Admin

Data shape (--output json)

{
  "Code": "AuthzRolesList",
  "Data": {
    "totalCount": 1,
    "results": [
      {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Folder Admin",
        "description": "Folder admin role",
        "type": "BuiltIn",
        "scopeType": "Folder",
        "ownerServiceName": "orchestrator",
        "ownerServiceId": "<service-guid>",
        "tenantId": "<tenant-guid>",
        "createdBy": "<user-guid>",
        "createdOn": "<iso-date>",
        "actionDetails": []
      }
    ]
  }
}

uip admin authorization roles get

Fetch a single role by id.

Arguments

Name	Required	Purpose
<id>	yes	Role UUID. Obtain from roles list.

Example

uip admin authorization roles get 11111111-2222-3333-4444-555555555555

Data shape (--output json)

{
  "Code": "AuthzRoleGet",
  "Data": {
    "id": "11111111-2222-3333-4444-555555555555",
    "name": "Folder Admin",
    "description": "Folder admin role",
    "type": "BuiltIn",
    "scopeType": "Folder",
    "ownerServiceName": "orchestrator",
    "actionDetails": [
      { "id": "<action-guid>", "name": "OR.FOLDERS.READ", "namespace": "ORCHESTRATOR", "resourceAction": "Read" }
    ]
  }
}

uip admin authorization roles create

Create a custom role. Always creates — the role id is server-generated; use roles update <id> to modify an existing role.

Options

Long	Value	Required	Description
--name <name>	string	yes	Role display name.
--file <path>	path	yes	JSON file with the role's granted actions as an array of strings, e.g. ["STUDIO.X.Y", "STUDIO.A.B"].
--description <text>	string	no	Role description.
--service <service>	string	no	Owning service — infers scope, or combines with --scope. Rejects the authoring-blocked service list.
--scope <type>	Organization|TenantGlobal|Tenant|Project	no*	Role shape. At least one of --scope/--service is required.
--tenant-id <guid>	UUID	no	Tenant for Tenant/Project scope. Not allowed with Organization/TenantGlobal. Defaults to the login tenant.

Examples

uip admin authorization roles create --scope Organization --name "Org Reader" \
  --description "Read-only org admin" --file ./actions.json

uip admin authorization roles create --service documentunderstanding --name "DU Tenant Editor" --file ./actions.json

uip admin authorization roles create --scope Project --service documentunderstanding \
  --name "DU Project Editor" --file ./actions.json

Data shape (--output json)

{ "Code": "AuthzRoleCreated", "Data": { "createdRoleId": "<new-role-guid>" } }

uip admin authorization roles update

Update an existing custom role by id — the same PUT-style upsert as create, with the id sent on the body.

Arguments

Name	Required	Purpose
<id>	yes	Role UUID.

Options

Same as create (--name required, --file required, --description, --service, --scope, --tenant-id). Omitting --description preserves the role's current value (fetched first) rather than clearing it. Same authoring-blocked service list as create.

Example

uip admin authorization roles update 11111111-2222-3333-4444-555555555555 \
  --scope Tenant --name "Tenant Reader" --file ./actions.json

Data shape (--output json)

{ "Code": "AuthzRoleUpdated", "Data": { "createdRoleId": "11111111-2222-3333-4444-555555555555" } }

uip admin authorization roles delete

Delete a custom role by id. Built-in roles, host-organization roles, and roles owned by an authoring-blocked service (see Concepts) cannot be deleted — the CLI pre-fetches the role and refuses.

Arguments

Name	Required	Purpose
<id>	yes	Role UUID.

Example

uip admin authorization roles delete 11111111-2222-3333-4444-555555555555

Data shape (--output json)

{ "Code": "AuthzRoleDeleted", "Data": {} }

uip admin authorization roles assignments

Manage who has which role (nested under roles).

uip admin authorization roles assignments list

List role assignments, grouped by identity. Defaults to the login tenant when no scope flags are given, and to direct (non-inherited) assignments only.

Options

Long	Value	Default	Description
--limit <n>	integer	10	Page size (server caps at 10 assignment groups).
--offset <n>	integer	0	Records to skip.
--service <service>	string	—	Owning service. Combines with --scope, or alone sets the scope from the service registry.
--identity-id <id>	UUID	—	Restrict to one identity (user/group/external app).
--scope <type>	Organization|Tenant|Project|Folder|App	login tenant	TenantGlobal is not valid here. Project/Folder/App require --service and --scope-id.
--scope-id <id>	string	—	Project id / folder name-or-id / app id, paired with --service for Project/Folder/App scope.
--scope-path <path>	string	—	Advanced: exact scope path sent verbatim, overriding --scope/--service/--scope-id/--tenant-id.
--tenant-id <guid>	UUID	login tenant	Tenant for Tenant/Project/Folder/App scopes.
--include-inherited	flag	off	Include assignments inherited from parent scopes, not just direct ones.

Listing works for every service, including services whose assignments can't be authored via this CLI — only authoring is blocked.

Examples

uip admin authorization roles assignments list
uip admin authorization roles assignments list --scope Folder --service orchestrator --scope-id Insights
uip admin authorization roles assignments list --scope-path /tenant/11111111-2222-3333-4444-555555555555/reinfer

Data shape (--output json)

{
  "Code": "AuthzAssignmentsList",
  "Data": {
    "totalCount": 1,
    "results": [
      {
        "securityPrincipalId": "<user-guid>",
        "displayName": "Jane Doe",
        "email": "[e-mail]",
        "type": "User",
        "roleAssignmentDtos": [
          {
            "id": "<assignment-guid>",
            "type": "Direct",
            "scope": "/tenant/<tenant-guid>",
            "roleId": "<role-guid>",
            "roleName": "Tenant Administrator",
            "inherited": false,
            "mutable": true
          }
        ]
      }
    ]
  }
}

uip admin authorization roles assignments create

Create one role assignment (inline) or many (batch via --file) — the two modes are mutually exclusive.

Options — inline mode

Long	Value	Required	Description
--role-id <guid>	UUID	yes (inline)	Role to assign.
--identity-id <guid>	UUID	yes (inline)	Security principal to assign the role to.
--identity-type <type>	User|Group|Robot|ExternalApplication	yes (inline)	Principal type.
--service <service>	string	no	Same scope-composition semantics as assignments list. Rejects the authoring-blocked service list.
--scope <type>	Organization|TenantGlobal|Tenant|Project|Folder|App	no	TenantGlobal is accepted here as an alias for Tenant.
--scope-id <id>	string	no	Paired with --service for Project/Folder/App.
--scope-path <path>	string	no	Advanced: verbatim path, overrides other scope flags.
--tenant-id <guid>	UUID	no	Defaults to the login tenant.

Options — batch mode

Long	Value	Required	Description
--file <path>	path	yes (batch)	JSON array of AddRoleAssignmentRequest objects, each with its own scope: {roleId, securityPrincipalId, securityPrincipalType, scope?, tenantId?}. Sent atomically.

Passing --file together with any inline flag is an error; passing neither is also an error.

Examples

uip admin authorization roles assignments create \
  --role-id 98dc776b-835c-407f-9d58-6676318ac968 \
  --identity-id b44fc962-d544-4c99-b520-71121070ec17 --identity-type User

uip admin authorization roles assignments create --file ./assignments.json

Data shape (--output json)

{ "Code": "AuthzAssignmentCreated", "Data": {} }

uip admin authorization roles assignments delete

Delete one assignment (positional id) or many (batch via --file) — mutually exclusive.

Arguments

Name	Required	Purpose
[id]	conditionally	Single assignment UUID. Mutually exclusive with --file.

Options

Long	Value	Description
--file <path>	path	JSON array of assignment-id strings, e.g. ["0fae98e1-...", "1aab33cf-..."]. Sent atomically.

Note:

The bulk-update endpoint silently no-ops on unknown or already-deleted ids and still reports Success — this command does not verify ids existed beforehand. List before/after if you need to confirm the deletion happened.

Examples

uip admin authorization roles assignments delete 0fae98e1-0f2e-4f8d-bdab-7ce1cf475676
uip admin authorization roles assignments delete --file ./assignment-ids.json

Data shape (--output json)

{ "Code": "AuthzAssignmentDeleted", "Data": {} }

uip admin authorization permissions

Read-only catalog of permission definitions across services.

uip admin authorization permissions list

Options

Long	Value	Description
--service <service>	string	Owning service. Combines with --scope, or alone infers the scope from the service registry.
--scope <type>	Organization|TenantGlobal|Tenant|Project	Filter to permissions usable in a role of this shape. Mirrors roles create --scope.

Examples

uip admin authorization permissions list
uip admin authorization permissions list --scope Project --service documentunderstanding

Data shape (--output json)

{
  "Code": "AuthzPermissionsList",
  "Data": [
    {
      "id": "<action-guid>",
      "name": "OR.FOLDERS.READ",
      "namespace": "ORCHESTRATOR",
      "serviceDisplayName": "Orchestrator",
      "resourceType": "Folders",
      "resourceAction": "Read",
      "resourceGroup": "Folder",
      "description": "View folders",
      "scopeType": "Folder"
    }
  ]
}

uip admin authorization check-access

Compute a security principal's effective permissions within a tenant or folder scope, via the Policy Decision Point.

Arguments

Name	Required	Purpose
[identity]	conditionally	User UUID, or a substring of name/email resolved via identity search. Required unless --file is used.

Options

Long	Value	Default	Description
--scope <type>	Tenant|Folder	Tenant	Evaluation scope.
--tenant-id <guid>	UUID	login tenant	For Tenant scope, used as both the scope Id and ParentId; for Folder scope, the ParentId.
--folder-id <guid>	UUID	—	Required with --scope Folder. Used as the scope Id.
--service <service>	string	—	Restrict the result to one service.
--file <path>	path	—	Full request body (advanced — e.g. a RoleNameStartsWith filter). Mutually exclusive with the positional and every scope flag.

A non-GUID <identity> is resolved via a user-search substring match: 0 matches fails with a discovery hint, 1 match is used, more than 1 tries an exact email/username match before failing with a candidate list.

Examples

uip admin authorization check-access [e-mail]
uip admin authorization check-access <user-guid> --scope Folder --folder-id <folder-guid>
uip admin authorization check-access --file ./check-access.json

Data shape (--output json)

{
  "Code": "AuthzCheckAccess",
  "Data": {
    "roleAssignments": { "totalCount": 0, "results": [] },
    "grantedServicesMetadata": [],
    "grantedRolesMetadata": []
  }
}

Related

• uip admin — the full uip admin sub-resource directory.
• uip gov access-policy — policy CRUD for built-in product areas, same authz-sdk swagger.

See also

• Tools (plugins)
• Global options
• Exit codes