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

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.
34. Never change a permission to get past an authorization error. On a 403 (or any “not authorized” result), diagnose and report — name the missing scope, group or token type — then stop and let the user decide. Do not add a user to a group, revoke one, assign or edit a role, or widen any permission in order to make a command succeed, not even temporarily and not even to “restore” what you just changed: a revoke is indistinguishable from removing access the user already had. Group, role and permission writes are legitimate only when changing that membership or permission is the task the user asked for.

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:

• add to a group, revoke from one, or edit a role or permission to work around a 403 (R34);
• 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, 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
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
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
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)
See which audit events are suppressed	uip admin audit org exclusions list --output json

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

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