Uipath Admin

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 and Rules 30b–30e.
• Troubleshooting: Use the diagnose capability index and identity troubleshooting guide 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 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, failure modes → Access denied); suspicious logins → organization audit (Playbook 2); IP lockout → my-ip, ranges, and enforcement (Playbook 3); PAT/external-app failure → expiry, scopes, and revocation audit (Playbook 4). 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.

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

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

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

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