# 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`](./uip-admin.md) 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`](./uip-gov.md) — 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

```text
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](#concepts)) — only authoring is blocked.

#### Examples

```bash
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)

```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

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

#### Data shape (--output json)

```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

```bash
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)

```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

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

#### Data shape (--output json)

```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](#concepts)) cannot be deleted — the CLI pre-fetches the role and refuses.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<id>` | yes | Role UUID. |

#### Example

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

#### Data shape (--output json)

```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

```bash
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)

```json
{
  "Code": "AuthzAssignmentsList",
  "Data": {
    "totalCount": 1,
    "results": [
      {
        "securityPrincipalId": "<user-guid>",
        "displayName": "Jane Doe",
        "email": "jane.doe@acme.example",
        "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

```bash
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)

```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

```bash
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)

```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

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

#### Data shape (--output json)

```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

```bash
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
```

### Data shape (--output json)

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

## Related

- [`uip admin`](./uip-admin.md) — the full `uip admin` sub-resource directory.
- [`uip gov access-policy`](./uip-gov.md) — policy CRUD for built-in product areas, same authz-sdk swagger.

## See also

- [Tools (plugins)](./concepts-tools.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)