UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

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 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​
LongValueDefaultDescription
--limit <n>integer20Page size.
--offset <n>integer0Records 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
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": []
      }
    ]
  }
}
{
  "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​
NameRequiredPurpose
<id>yesRole UUID. Obtain from roles list.
Example​
uip admin authorization roles get 11111111-2222-3333-4444-555555555555
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" }
    ]
  }
}
{
  "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​
LongValueRequiredDescription
--name <name>stringyesRole display name.
--file <path>pathyesJSON file with the role's granted actions as an array of strings, e.g. ["STUDIO.X.Y", "STUDIO.A.B"].
--description <text>stringnoRole description.
--service <service>stringnoOwning service — infers scope, or combines with --scope. Rejects the authoring-blocked service list.
--scope <type>Organization|TenantGlobal|Tenant|Projectno*Role shape. At least one of --scope/--service is required.
--tenant-id <guid>UUIDnoTenant 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
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>" } }
{ "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​
NameRequiredPurpose
<id>yesRole 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
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" } }
{ "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​
NameRequiredPurpose
<id>yesRole UUID.
Example​
uip admin authorization roles delete 11111111-2222-3333-4444-555555555555
uip admin authorization roles delete 11111111-2222-3333-4444-555555555555
Data shape (--output json)​
{ "Code": "AuthzRoleDeleted", "Data": {} }
{ "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​
LongValueDefaultDescription
--limit <n>integer10Page size (server caps at 10 assignment groups).
--offset <n>integer0Records 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|Applogin tenantTenantGlobal 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>UUIDlogin tenantTenant for Tenant/Project/Folder/App scopes.
--include-inheritedflagoffInclude 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
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": "[email protected]",
        "type": "User",
        "roleAssignmentDtos": [
          {
            "id": "<assignment-guid>",
            "type": "Direct",
            "scope": "/tenant/<tenant-guid>",
            "roleId": "<role-guid>",
            "roleName": "Tenant Administrator",
            "inherited": false,
            "mutable": true
          }
        ]
      }
    ]
  }
}
{
  "Code": "AuthzAssignmentsList",
  "Data": {
    "totalCount": 1,
    "results": [
      {
        "securityPrincipalId": "<user-guid>",
        "displayName": "Jane Doe",
        "email": "[email protected]",
        "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​
LongValueRequiredDescription
--role-id <guid>UUIDyes (inline)Role to assign.
--identity-id <guid>UUIDyes (inline)Security principal to assign the role to.
--identity-type <type>User|Group|Robot|ExternalApplicationyes (inline)Principal type.
--service <service>stringnoSame scope-composition semantics as assignments list. Rejects the authoring-blocked service list.
--scope <type>Organization|TenantGlobal|Tenant|Project|Folder|AppnoTenantGlobal is accepted here as an alias for Tenant.
--scope-id <id>stringnoPaired with --service for Project/Folder/App.
--scope-path <path>stringnoAdvanced: verbatim path, overrides other scope flags.
--tenant-id <guid>UUIDnoDefaults to the login tenant.
Options — batch mode​
LongValueRequiredDescription
--file <path>pathyes (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
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": {} }
{ "Code": "AuthzAssignmentCreated", "Data": {} }

uip admin authorization roles assignments delete​

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

Arguments​
NameRequiredPurpose
[id]conditionallySingle assignment UUID. Mutually exclusive with --file.
Options​
LongValueDescription
--file <path>pathJSON 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
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": {} }
{ "Code": "AuthzAssignmentDeleted", "Data": {} }

uip admin authorization permissions​

Read-only catalog of permission definitions across services.

uip admin authorization permissions list​

Options​
LongValueDescription
--service <service>stringOwning service. Combines with --scope, or alone infers the scope from the service registry.
--scope <type>Organization|TenantGlobal|Tenant|ProjectFilter 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
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"
    }
  ]
}
{
  "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​

NameRequiredPurpose
[identity]conditionallyUser UUID, or a substring of name/email resolved via identity search. Required unless --file is used.

Options​

LongValueDefaultDescription
--scope <type>Tenant|FolderTenantEvaluation scope.
--tenant-id <guid>UUIDlogin tenantFor 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 alice@example.com
uip admin authorization check-access <user-guid> --scope Folder --folder-id <folder-guid>
uip admin authorization check-access --file ./check-access.json
uip admin authorization check-access [email protected]
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": []
  }
}
{
  "Code": "AuthzCheckAccess",
  "Data": {
    "roleAssignments": { "totalCount": 0, "results": [] },
    "grantedServicesMetadata": [],
    "grantedRolesMetadata": []
  }
}

See also​

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated