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

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

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 for organization hierarchy and distinctions among users, groups, robot accounts, robot credentials, and external apps.

Output Etiquette and Report Contract

Task Navigation