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.
• 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

1. Discover before creating: List robot accounts, groups, and external apps first; user invites are excepted.
2. Show secrets once only for external-app creation and generate-secret; tell the user to save them immediately.
3. External apps require creation scopes: --app-scope or --user-scope, such as --app-scope "OR.Folders".
4. Group membership uses user IDs: Resolve users under Rule 5, then use groups members add/revoke.
5. 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

1. 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).
2. 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.
3. --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).
4. 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.
5. 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.
6. Assignment create/delete requires principal resolution under Rule 5; --identity-id is an unchecked raw UUID.
7. 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

1. 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).
2. tenants delete is soft-only. Restoration requires support; no hard-delete flag exists.
3. Tenant commands default to the login tenant. Always provide explicit <TENANT_ID> for tenant delete/disable and tenants services remove.
4. Resolve region before tenant creation: Run organizations regions list first because --region is required and region-aware.
5. Service disable/remove can falsely report Success. Always re-list afterward. See [Tenants concepts](references/tenants-commands.md#concepts-and-safety-rules).

Audit

1. 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).
2. Events return {auditEvents, next, previous}, not a bare array. Read Data.auditEvents[]; next is newer, previous older, and newest-backward traversal follows previous.
3. --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.”
4. Run audit <scope> sources first. Never invent source, target, or type GUIDs; use live catalog GUIDs. The response also answers availability questions.
5. 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).

1. --tenant-id is ignored for org audit. Use audit tenant instead.
2. 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.

1. 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.

IP Restriction

1. 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).
2. IP-lockout recovery is platform-side: use an allowlisted IP to disable enforcement or Portal recovery; there is no CLI bypass.
3. 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);
• confuse provisioned services list with the list-available catalog (R22), or run an OMS mutation without echoing the resolved target (Output Etiquette).

Quick Start

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

Task Navigation