---
name: uipath-admin
description: "UiPath Admin via `uip admin` — Identity Server (users, groups, robot accounts, external OAuth2 apps, secrets, PATs, SMTP), Authorization (custom roles, role assignments, permission catalog, effective-access check-access PDP), OMS (org read/update, tenant lifecycle, service provisioning, regions, async op polling), IP Restriction (allowlist, enforcement, bypass rules, lockout safety), and Audit via `uip admin audit` (event sources, paginated queries, JSON-folder or CSV export, exclusion rules). Troubleshoot access-denied, login failures, role misconfig, IP lockout, PAT/app auth. Owns ALL org/tenant/identity audit — use `uip admin audit`, NOT `uip or audit-logs`, for any audit logs / audit trail / audit events / export / login history / who-did-what request. Also owns audit exclusion rules: stop, suppress, or mute recording of chosen audit events (`audit org exclusions`). Orchestrator-specific roles/permissions/folders/jobs→uipath-platform. RPA workflows→uipath-rpa."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
---

# UiPath Admin

Administrative operations through `uip admin` for Identity Server, Authorization, OMS, IP Restriction, and Audit.

## When to Use

- **Identity:** Users, groups and membership, robot accounts, external apps and credentials, PATs, SMTP, OAuth2 scope discovery, and human or robot onboarding.
- **Authz:** Custom roles, assignments, permission catalogs, effective access, and ad-hoc grants. Role scopes are `Organization`, `TenantGlobal`, `Tenant`, and `Project`; assignments may also use `Folder` or `App`.
- **OMS:** Current organization, tenant lifecycle, service provisioning, operation polling, and region discovery. The CLI cannot create or delete organizations.
- **IP Restriction:** Allowlist entries, enforcement, bypass rules, and `ip-restriction my-ip` for public-IP questions and safety checks.
- **Audit:** Use `uip admin audit`, never `uip or audit-logs`, for organization or tenant audit events, sources, targets, types, queries, login history, membership/license activity, tenant activity, investigations, and exports. `uip or audit-logs` is Orchestrator-operational audit and belongs to `uipath-platform`.
- **Audit exclusions:** Use `uip admin audit org exclusions` for the rules that stop the trail recording matching events — "stop/suppress/mute recording these events", "our audit trail is too noisy", "which events are we not recording", or any list/get/create/update/delete of an exclusion rule. Organization-scoped only. Every write suppresses evidence, so follow [audit-exclusions-guide.md](references/audit-exclusions-guide.md) and Rules 30b–30e.
- **Troubleshooting:** Use the [diagnose capability index](references/diagnose/CAPABILITY.md) and [identity troubleshooting guide](references/identity-troubleshoot-guide.md) for access, authentication, identity, tenant operations, provisioning, robot authentication, SMTP, PAT, external-app, or IP-lockout symptoms.

For audit availability, run `uip admin audit <scope> sources`; discover live catalogs instead of relying on memory. Route `org` versus `tenant` with [audit-workflow-guide.md → Audit scope disambiguation](references/audit-workflow-guide.md#scope-selection) and Rule 23. Natural-language investigations may cover resource changes/deletions, sign-ins, tenant changes, compliance windows, and cross-scope requests; run once per requested scope and combine results.

Troubleshooting routes: access denied — 403, "role not taking effect", and cross-service role confusion are **one** scenario → resolve the principal, check effective access, look up the required permission, then branch on missing permission versus mis-scoped grant ([Playbook 1](references/identity-troubleshoot-guide.md#playbook-1--access-denied-http-403), [failure modes → Access denied](references/diagnose/failure-modes.md#access-denied-http-403)); suspicious logins → organization audit ([Playbook 2](references/identity-troubleshoot-guide.md#playbook-2--suspicious-login-activity)); IP lockout → `my-ip`, ranges, and enforcement ([Playbook 3](references/identity-troubleshoot-guide.md#playbook-3--ip-restriction-lockout)); PAT/external-app failure → expiry, scopes, and revocation audit ([Playbook 4](references/identity-troubleshoot-guide.md#playbook-4--pat-or-external-app-not-working)). SMTP uses `smtp get` and `smtp test`; poll stuck tenant operations; for provisioning no-ops check platform-pinned services; distinguish robot identity issues from credential-model issues.

## Critical Rules

Each rule is part of the agent contract.

### Universal

1. **Route correctly:** Orchestrator-specific role/permission requests go to `uip or roles` (`uipath-platform`), not `uip admin authorization`. Organization/tenant audit always uses `uip admin audit <scope>` (`sources`, `events`, or `export`), never `uip or audit-logs`, including audit history, exports, login history, compliance dumps, and “who did what/where.”
2. **Verify login first:** Run `uip login status --output json`. If unauthenticated, stop and ask the user to run `uip login`; it opens an interactive browser flow and must not run in automated/non-interactive sessions. Environment-authenticated sessions are already logged in. Resolve the organization from the active session.
3. **Use `--output json` on every command.** Parse programmatically and present conversationally.
4. **Stop on error and show it verbatim.** Never retry authentication failures; ask the user to run `uip login`.
5. **Resolve named principals before high-risk operations:** users, groups, robot accounts, and external apps, including assignment create/delete, user/group deletion, membership changes, robot deletion, external-app deletion, and secret generation. Search first and echo `Principal: <displayName> (<userName>) — <id>`. Zero matches: stop and ask. Multiple matches: show a numbered list and wait for a digit. Never substitute the current login user. See [Resolving Principal IDs](references/authorization/role-assignment-management.md#resolve-principals-before-mutation).

### Identity

6. **Discover before creating:** List robot accounts, groups, and external apps first; user invites are excepted.
7. **Show secrets once only** for external-app creation and `generate-secret`; tell the user to save them immediately.
8. **External apps require creation scopes:** `--app-scope` or `--user-scope`, such as `--app-scope "OR.Folders"`.
9. **Group membership uses user IDs:** Resolve users under Rule 5, then use `groups members add/revoke`.
10. **Confirm deletion** of users, groups, robot accounts, and external apps after resolving the target. Built-in groups (`type: "BuiltIn"`) cannot be deleted; only `Custom` groups can.

### Authz

11. **Built-in roles are read-only.** Create/update/delete only `Custom` roles. The CLI rejects service-managed or platform-level authoring; see [Services That Manage Their Own Roles](references/authorization/role-management.md#services-and-role-ownership).
12. **`roles create/update` are PUT-style upserts.** Build the body from flags and `--file ./actions.json`; always `roles get` before update because omitted flags overwrite fields.
13. **`--service` infers scope** (for example, `studio` → `Tenant`, `apps` → `Organization`); use `--scope` only to override. **Never guess a `serviceName`** — valid values and the re-derive command: [permission-catalog.md → serviceNames](references/authorization/permission-catalog.md#--service-servicenames-and-how-to-re-derive-them).
14. **Listing supports every service; authoring does not.** `roles list --service <svc>` and `roles assignments list --service <svc>` accept every service. Use `check-access` for effective access.
15. **Scope vocabularies differ:** `roles create --scope` = `Organization|TenantGlobal|Tenant|Project`; assignment create adds `Folder|App`; assignment list excludes `TenantGlobal`; `check-access --scope` supports only `Tenant|Folder`.
16. **Assignment create/delete requires principal resolution** under Rule 5; `--identity-id` is an unchecked raw UUID.
17. **Assignment ownership must match the scope path:** the path's service segment is `lowercase(ownerServiceName)`, taken verbatim from the role's own `roles get` — `DocumentUnderstanding` → `/tenant/<tid>/documentunderstanding`. `CentralizedAccess` has no service segment (`/` or `/tenant/<tid>`). Never substitute a sibling service's segment and never copy one off another role's grant: `Reinfer` (display name **IXP**) is not Document Understanding. Display-name mappings apply to user-facing prose only, never to paths. Repair a mismatch by re-creating the assignment with `--service <slug>` or `--scope-path "/tenant/<tid>/<slug>"`; a `Tenant`-scope role takes no project segment. See [Validate Role's Owning Service](references/authorization/role-assignment-management.md#validate-role-service-binding-and-scope-path).
17b. **A mis-scoped grant is invisible to the default listings — retrieve it with `--scope-path`.** `roles assignments list` pins both a scope path and a serviceName from your flags, so a `<svc>`-owned role granted at the bare `/tenant/<tid>` matches no default shape: it is absent from the bare listing, from `--identity-id`, from `--scope Tenant` (with or without `--include-inherited`), and from `--service <svc>`. Retrieve it with `roles assignments list --scope-path "/tenant/<TENANT_ID>" --output json` and no `--service`. Never read an empty listing as proof the grant does not exist, and never re-create the assignment on that basis — that reproduces the original mismatch. See [Access denied → Cause B](references/diagnose/failure-modes.md#cause-b--the-permission-is-granted-at-the-wrong-scope).

### OMS

18. **Async lifecycle: auto-poll, then hand off.** Tenant create/update/delete/enable/disable return `operationId`; poll `organizations operation get <OP_ID>` three times at five-second intervals, stop on terminal status, then, if still in progress, present a numbered menu. Never loop indefinitely. Organizations create/delete are unavailable in the CLI and require Portal/support. See [Polling procedure](references/organization-management.md#polling-procedure-auto-poll-then-hand-off).
19. **`tenants delete` is soft-only.** Restoration requires support; no hard-delete flag exists.
20. **Tenant commands default to the login tenant.** Always provide explicit `<TENANT_ID>` for tenant delete/disable and `tenants services remove`.
21. **Resolve region before tenant creation:** Run `organizations regions list` first because `--region` is required and region-aware.
22. **Service disable/remove can falsely report Success.** Always re-list afterward. See [Tenants concepts](references/tenants-commands.md#concepts-and-safety-rules).

### Audit

23. **Disambiguate `org` versus `tenant` before querying.** If vague and no prior turn fixes scope, ask one clarifying question, using AskUserQuestion when available; do not silently default. If non-interactive clarification is impossible, query both and combine. Scope is positional: `uip admin audit org sources` or `uip admin audit tenant events`; `--scope` is invalid. See [Audit scope disambiguation](references/audit-workflow-guide.md#scope-selection).
24. **Events return `{auditEvents, next, previous}`**, not a bare array. Read `Data.auditEvents[]`; `next` is newer, `previous` older, and newest-backward traversal follows `previous`.
25. **`--limit` paginates internally.** Do not date-loop for pagination. Each server request is clamped to `[10, 200]`; CLI limits are up to 10000. `--limit` must be `[1, 10000]`; above 10000 returns `Result: "ValidationError"`. Omit it or stay within range for “everything.”
26. **Run `audit <scope> sources` first.** Never invent source, target, or type GUIDs; use live catalog GUIDs. The response also answers availability questions.
27. **Bound event windows in UTC ISO 8601.** Do not query noisy tenants without `--from-date` and `--to-date`. Accept date-only or timestamp forms such as `2026-04-01T14:30:00Z`. `--to-date` includes the exact instant; use the next day’s start or `T23:59:59.999Z` for a full final day. Resolve relative dates using actual UTC (`date -u`), never guessing, and echo the window.
27b. **An empty targeted query is complete.** State that no matching event was found, with scope, filters, and window; offer widening, the other scope, or checking resource existence. Never infer an actor from adjacent resources, event types, or broad searches, and never loosen filters merely to find a culprit. Name an actor only when the matching event supports both requested resource and verb; quote `createdOn` and identifying `eventDetails`. See [Step 5](references/audit-workflow-guide.md#step-5--report-no-match-safely).
28. **`--tenant-id` is ignored for org audit.** Use `audit tenant` instead.
29. **On audit 401, do not retry.** The token lacks `Audit.Read`; tell the user to run `uip logout && uip login`.
29b. **Retry transient audit 5xx errors** (`ErrorCode: server_error` / `Retry: RetryLater`, such as 503/504) up to two more times with several seconds of backoff, using the identical query. Do not change limit or window. Never present or save an error envelope as data; report failed retrieval.
30. **Exports use a base directory and whole UTC days.** Require `--from-date`, `--to-date`, and `--output-path`. Dates are inclusive calendar days; do not use the events next-day trick. `--output-path` is a directory, never a filename/extension; the CLI creates `audit_<from>_<to>_<generated-at>` inside it. Default JSON creates per-day `<YYYY-MM-DD>.json`; `--file-format csv` creates one merged CSV. Use CSV for flat spreadsheets and JSON for day-wise files. Pass a user-named destination verbatim without confirmation; confirm only a selected default such as `./audit-exports`. Report `Path` and `GeneratedAt`.

30b. **Exclusion rules are organization-scoped, and a rule must constrain something.** `uip admin audit org exclusions <list|get|create|update|delete>`; there is no `audit tenant exclusions` — limit a rule to tenants with an `--exclude-tenant` selector instead. One selector per dimension: `--exclude-tenant`, `--source`, `--target`, `--type` (each repeatable) and `--status` (single-valued, `Success` or `Failure`). **The tenant selector is `--exclude-tenant`, never `--tenant-id`** — that flag means "run against this tenant" on the read verbs and is not an option here. Values inside a selector are OR-ed and selectors are AND-ed. At least one selector is required, because a rule constraining nothing would exclude every event in the organization; never satisfy a vague "mute the audit noise" by creating one. Discover selector GUIDs with `audit org sources` and never invent them (Rule 26). `enforcement` is not a flag — `Exclude` is the only value. A rule name may not be a bare GUID. See [audit-exclusions-guide.md](references/audit-exclusions-guide.md).

30c. **Every exclusion write suppresses evidence — state the impact and get explicit confirmation first.** Before `create`, `update`, or `delete`, show the rule's selectors translated to names from `audit org sources` (never bare GUIDs) and say: exclusion starts when the rule activates and is never retroactive; events already recorded are unaffected; events suppressed from then on cannot be recovered, because deleting the rule resumes recording without restoring the gap. Wait for the user's confirmation. Never widen a rule beyond what the user asked for, never delete a rule you did not create to get past `RuleLimitExceeded` or `OverlappingRuleExists`, and never chain writes — create one rule, verify it with `exclusions get`, report `PolicyId` plus `ActivatedOn`, then stop.

30d. **`exclusions update` is a full replacement, not a patch — and it re-activates.** `get`, `update`, and `delete` take one `<rule>` positional that accepts the rule's **name or** its policy id; prefer the name the user gave, and pass `<rule>` before the selector flags, which are variadic and would read it as another value. Run `exclusions get "<RULE>" --output json` first, then resend every selector the rule should keep — an omitted field is dropped, so renaming with `--name` alone strips the rule's selectors. **Activation is part of the replacement:** without `--inactive` the rule comes back active, so replacing a deliberately staged rule starts it suppressing events — check `IsActive` on the `get` and pass `--inactive` again when it was false. `--file` supplies the whole body instead and cannot be combined with any inline flag; a body carries only camelCase `name`, `enforcement`, `isActive`, and `selectors` (`isActive` defaults to true when omitted), so a `get` response — PascalCased, with server-owned `policyId` and timestamps — is rejected rather than trimmed. To swap a rule without a recording gap, stage the replacement with `--inactive`, delete the old rule, then activate the new one.

30e. **An exclusions failure names its own cause — act on `Instructions`, do not improvise.** Rejections carry the service's reason in `Message` and a machine-readable code in `Context.errorCode` (`OverlappingRuleExists`, `UnknownSelectorValue`, `SelectorValueNotPermitted`, `DuplicateRuleName`, …); a local `Result: ValidationError` (exit `3`) never reached the network, so fix the command instead of retrying it. **When a `<rule>` name matches both an active and an inactive rule the CLI refuses to guess** — it returns `ValidationError` listing both policy ids; ask the user which one or pass the id, and never default to the active one, because a staged replacement is exactly what the other rule is. `SelectorValueNotPermitted` is by design — UiPath monitoring events and audit-configuration changes, including changes to the rules themselves, can never be excluded; report the refusal rather than re-spelling the target. `unknown command 'exclusions'` means the installed CLI predates the feature (tell the user to upgrade `@uipath/cli`); `HTTP 404` on `list` means this organization's audit service does not expose the rules API yet. Neither is retryable, and neither is a reason to fall back to `uip or audit-logs`. **An active rule also hides its events from `events` and `export` without marking the gap** — when a targeted investigation comes back empty, run `exclusions list` before concluding the action never happened (this explains the silence; it never licenses naming an actor, Rule 27b).

### IP Restriction

31. **Enforcement enable requires a safety check and confirmation:** Run `ip-restriction my-ip`, verify the caller IP is covered by `ip-ranges list`, then state: “After enabling IP restriction, any caller (Portal, CLI, robot, external app) whose source IP is not in `ip-ranges list` will be blocked from this org. Misconfiguration locks you out and requires platform-side recovery. Proceed?” Require `--confirm`. Deleting a range while enforcement is enabled also requires `--confirm`. See [enforcement management](references/ip-restriction/enforcement-management.md).
32. **IP-lockout recovery is platform-side:** use an allowlisted IP to disable enforcement or Portal recovery; there is no CLI bypass.
33. **Never expose “APMS.”** Say “IP Restriction” in user-facing output.

## What Not to Do

1. **Never pass resource IDs as flags.** IDs and names are positional, for example `groups members add <GROUP_ID> --user-ids ...`; apply this to get/update/delete/create commands.
2. **Never present authz results without provenance:** role name, `scopeType`, `ownerServiceName`, and tenant binding using names rather than UUIDs. See [Provenance contract](references/authorization/authorization-commands.md#provenance-contract-for-completion-output).

The rest are the inverse of the Critical Rules — never:
- use `uip or audit-logs` for org/tenant audit (R1), or default the audit scope when ambiguous (R23);
- treat `audit events` as a bare array (R24), hand-loop dates to paginate (R25), invent source/target/type GUIDs (R26), or query events unbounded on a noisy tenant (R27);
- name an actor the query didn't return (R27b), pass `--tenant-id` to `org` audit (R28), retry a 401 (R29), or save/report an error envelope as data (R29b);
- use the next-day `--to-date` trick on `export` (R30), or `roles update` with only the changed flag (R12);
- reach for `audit tenant exclusions`, create a selector-less exclusion rule, or invent a selector GUID (R30b);
- write an exclusion rule without stating the impact and getting confirmation, or present one as retroactive (R30c);
- pass `--tenant-id` to an exclusions command, or `--status` twice (R30b);
- `exclusions update` with only the changed flag, drop `--inactive` when replacing a staged rule, mix `--file` with inline flags, or feed a `get` response back into `--file` (R30d);
- retry a `SelectorValueNotPermitted` refusal or an `unknown command` / 404 on `exclusions`, or pick a rule yourself when a `<rule>` name is ambiguous (R30e);
- confuse provisioned `services list` with the `list-available` catalog (R22), or run an OMS mutation without echoing the resolved target (Output Etiquette).

## Quick Start

| Goal | Entry point |
|---|---|
| Invite user and assign group | [user-management.md](references/user-management.md), [group-management.md](references/group-management.md) |
| Create custom role | `uip admin authorization roles create --scope <Organization\|TenantGlobal\|Tenant\|Project> --name "<NAME>" --file ./actions.json --output json` |
| Grant permissions | [grant-permissions.md](references/authorization/grant-permissions.md) |
| Assign a role | Resolve principal; `roles get`; validate owner service/path; create assignment |
| Check effective access | `uip admin authorization check-access <USER_GUID_OR_EMAIL> --scope <Tenant\|Folder> --output json` |
| Create tenant | [tenant-management.md](references/tenant-management.md) |
| Add tenant service | `tenants services list-available --region <R>`; add; verify post-state |
| Find public IP | `ip-restriction my-ip --output json`; return `Data.ipAddress` |
| Enable IP enforcement | `my-ip` → verify range → `enforcement enable --confirm` |
| Query/export audit | [audit-workflow-guide.md](references/audit-workflow-guide.md) |
| Stop recording noisy audit events | `audit org sources` → propose + confirm → `uip admin audit org exclusions create --name "<RULE_NAME>" --type <EVENT_TYPE_ID> --status Success --output json` → verify with `exclusions get "<RULE_NAME>"` (Rules 30b–30e, [audit-exclusions-guide.md](references/audit-exclusions-guide.md)) |
| See which audit events are suppressed | `uip admin audit org exclusions list --output json` |

## Key Concepts

See [key-concepts.md](references/key-concepts.md) for organization hierarchy and distinctions among users, groups, robot accounts, robot credentials, and external apps.

## Output Etiquette and Report Contract

| Area | Required output |
|---|---|
| Identity mutations | Result and new resource ID; highlight one-time external-app secrets, warn to save them, and offer a relevant next step. |
| Authz reads/mutations | Role name, `scopeType`, `ownerServiceName` from the response, translated display name where applicable, and tenant binding resolved to a name. For `check-access`, label each row `direct` or `inherited from <Group name>` using nested `roleAssignments[].securityPrincipalType`. See [Provenance contract](references/authorization/authorization-commands.md#provenance-contract-for-completion-output). |
| OMS reads | Lead with `Organization: <ORG_NAME>`; separate provisioned services with status from the available catalog without status. Tenant reads also show name, UUID, and lifecycle status. |
| OMS mutations | Echo resolved target; auto-poll async operations three times at five-second intervals, then offer a numbered menu; re-list synchronous services to verify state. |
| Audit queries/exports | State scope, count, resolved UTC window, filters, and cursor state; obey Rules 23, 26, and 27. After reporting, wait for the user's next-step choice and do not chain mutations. For exports report `Path` and `GeneratedAt`. See [audit output etiquette](references/audit-workflow-guide.md#output-etiquette--after-every-audit-query-or-export). |
| Audit exclusion reads | Rule count and how many are active; each rule's selectors translated to names from `audit org sources`, never bare GUIDs; `IsActive` plus `ActivatedOn` per rule. |
| Audit exclusion writes | Before writing, state the impact and obtain explicit confirmation (Rule 30c). After: `PolicyId`, `IsActive`, `ActivatedOn`, which events stop being recorded and from when, and — on a delete — that recording resumes now while the existing gap remains. Offer one next step and wait; never chain another write. See [audit-exclusions-guide.md](references/audit-exclusions-guide.md#output-etiquette--after-an-exclusions-call). |
| IP Restriction mutations | Before enabling, state impact and obtain explicit confirmation; afterward rerun `my-ip` and `ip-ranges list` to confirm coverage; never say APMS. |

## Task Navigation

| Need | Reference |
|---|---|
| Identity CLI | [identity-commands.md](references/identity-commands.md) |
| Users | [user-management.md](references/user-management.md) |
| Groups and membership | [group-management.md](references/group-management.md) |
| Robot accounts | [robot-account-management.md](references/robot-account-management.md) |
| External apps | [external-app-management.md](references/external-app-management.md) |
| PATs | [pat-management.md](references/pat-management.md) |
| SMTP | [smtp-management.md](references/smtp-management.md) |
| Authorization CLI | [authorization-commands.md](references/authorization/authorization-commands.md) |
| Custom roles | [role-management.md](references/authorization/role-management.md) |
| Grant permissions | [grant-permissions.md](references/authorization/grant-permissions.md) |
| Role assignments | [role-assignment-management.md](references/authorization/role-assignment-management.md) |
| Permission catalog | [permission-catalog.md](references/authorization/permission-catalog.md) |
| Effective access | [check-access.md](references/authorization/check-access.md) |
| Organizations | [organizations-commands.md](references/organizations-commands.md), [organization-management.md](references/organization-management.md) |
| Tenants and services | [tenants-commands.md](references/tenants-commands.md), [tenant-management.md](references/tenant-management.md) |
| IP Restriction CLI | [ip-restriction-commands.md](references/ip-restriction/ip-restriction-commands.md) |
| IP ranges | [ip-range-management.md](references/ip-restriction/ip-range-management.md) |
| Enforcement | [enforcement-management.md](references/ip-restriction/enforcement-management.md) |
| Bypass rules | [bypass-rule-management.md](references/ip-restriction/bypass-rule-management.md) |
| Audit CLI | [audit-commands.md](references/audit-commands.md) |
| Audit investigations | [audit-workflow-guide.md](references/audit-workflow-guide.md) |
| Audit exclusion rules (stop recording events) | [audit-exclusions-guide.md](references/audit-exclusions-guide.md), surface in [audit-commands.md](references/audit-commands.md#uip-admin-audit-org-exclusions) |
| Audit pagination | [audit-commands.md](references/audit-commands.md) plus Rule 25 |
| Troubleshooting | [identity-troubleshoot-guide.md](references/identity-troubleshoot-guide.md) |
| Diagnostic capability index | [diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md) |
| Failure modes | [failure-modes.md](references/diagnose/failure-modes.md) |
| Diagnostic priority ladder | [troubleshooting-guide.md](references/diagnose/troubleshooting-guide.md) |