uipath-admin

# UiPath Admin Administrative operations on UiPath via `uip admin` — Identity Server, Authorization, OMS, IP Restriction, Audit. Per-area workflows, command references, and procedures are in the linked files below — this file is the entry contract. ## When to Use This Skill ### Identity - **Manage identity users** — list, create, invite, update, delete - **Manage groups** — CRUD + add/remove members - **Manage robot accounts** — create, update, delete unattended robot identities - **Manage external apps** — OAuth2 clients, secrets, federated credentials - **Manage personal access tokens (PATs)** — create, list, revoke, regenerate - **Configure SMTP** — get, update, test, delete email settings - **Browse OAuth2 scopes** — list available scopes for external apps and PATs - **Onboard human user** — invite, assign to groups - **Onboard robot account** — create account, assign to groups ### Authz - **Manage custom roles** — CRUD on Authorization service role definitions (scope shapes: `Organization`, `TenantGlobal`, `Tenant`, `Project`) - **Manage role assignments** — assign roles to users/groups/robot accounts at `Organization`, `Tenant`, `TenantGlobal`, `Project`, `Folder`, or `App` scope - **List permission definitions** — read-only catalog of permissions across services - **Check effective access** — compute what a principal can actually do at a given scope (Policy Decision Point) - **Grant permission(s) to a principal** — ad-hoc "grant me X" / "give <user> Y, Z" requests resolved via the scope/service intersection flow ### OMS - **Inspect / update the current organization** — `uip admin organizations` (read + update only; no CLI create/delete) - **Manage tenant lifecycle** — create, enable, disable, delete tenants in the caller's org - **Provision org-level or tenant-level services** — `services list`, `list-available`, `add`, `enable`, `disable`, `remove` - **Poll async OMS operations** — `tenants` mutations return `operationId`; poll via `organizations operation get <id>` (the canonical poll endpoint) - **List available regions** — discover provisioning regions before `tenants create` ### IP Restriction - **Manage IP allowlisting** — add / update / delete CIDR entries that gate inbound access - **Toggle IP-restriction enforcement** — turn the org-wide allowlist switch on or off (with lockout safety) - **Manage bypass rules** — URL-pattern exceptions to IP allowlisting - **Look up the caller's public IP** — answer "what's my IP?" / "what public IP does the platform see for me?" directly with `ip-restriction my-ip`; also the safety pre-flight before enabling enforcement ### Audit Activate on both **explicit audit requests** and **natural-language investigation intent** — users rarely say "audit events" by name. > **Surface boundary — this is `uip admin audit`, not `uip or audit-logs`.** Every org/tenant audit ask below — including bare "audit logs", "audit history", "export the audit trail", "login history", "who did what" — is served by `uip admin audit <scope>`. Do **not** fall back to `uip or audit-logs` (Orchestrator-operational audit, a different schema; that's the `uipath-platform` skill), even when the user's wording is generic. When the user asks **what** audit events / sources are available or visible, answer by **running** `uip admin audit <scope> sources` — discover live, never describe from memory or the docs. - **Explicit** — `uip admin audit` commands; list sources / targets / types; query, filter, paginate, or export events; CSV or per-day-JSON dump of audit history for a window. - **Query audit events** — list event sources, filter events by source / target / type / user / status / time window at org or tenant scope - **Export audit events** — chunked download from the long-term store (one call per UTC day, atomic abort on any chunk failure) as a folder of day-wise JSON files (default) or a single merged CSV via `--file-format csv` - **Membership / license phrasings** — "who joined / left the organization", "who was made an admin", "license changes", "cross-tenant audit" - **Sign-in / authentication phrasings** — "failed/successful logins", "login history for user X", "who's been signing in" - **Tenant-activity phrasings** — "what happened on tenant X", "asset/queue/folder edits", "queue items processed", "job failures", "Action Center task changes", "Apps / AgentHub / Document Understanding / Integration Service / Test Manager activity" - **Cross-scope phrasings** — "everything everywhere" (run the flow once per scope and present combined) - **Investigation intent** (full-sentence form) — "Who deleted the X folder last Tuesday?", "Show me failed logins for user Y this month.", "What changed on tenant Z between Jan 1 and Feb 1?", "Give me the audit log for the last 30 days.", "Was the API key rotated by someone in our org?", "Export everything for compliance for Q4." > **Scope routing** (which phrasing → `org` vs `tenant`, and why) lives in [audit-workflow-guide.md → Audit scope disambiguation](references/audit-workflow-guide.md#audit-scope-disambiguation--route-by-user-phrasing). Critical Rule 23 governs the stop-and-ask requirement when scope is ambiguous. ### Troubleshoot Activate on **access/auth/identity troubleshooting** — users report symptoms, not audit verbs. - **Diagnose access denied** — "user can't access X", "403 on API", "new hire has no permissions" → resolve principal, check-access, inspect role assignments. Playbook: [identity-troubleshoot-guide.md → Playbook 1](references/identity-troubleshoot-guide.md#playbook-1--user-cant-access-resource-x) - **Investigate login failures** — "failed login attempts", "account compromised?", "suspicious sign-ins" → org-scoped audit login-history investigation. Playbook: [identity-troubleshoot-guide.md → Playbook 2](references/identity-troubleshoot-guide.md#playbook-2--suspicious-login-activity) - **Diagnose role misconfiguration** — "custom role doesn't work", "user has role but can't do X" → inspect role actions, verify scope alignment. Playbook: [identity-troubleshoot-guide.md → Playbook 3](references/identity-troubleshoot-guide.md#playbook-3--role-misconfiguration) - **Diagnose IP restriction lockout** — "can't access platform from new office", "all users blocked" → my-ip + ip-ranges list + enforcement get. Playbook: [identity-troubleshoot-guide.md → Playbook 4](references/identity-troubleshoot-guide.md#playbook-4--ip-restriction-lockout) - **Diagnose PAT / external app failures** — "API returns 401", "PAT stopped working", "external app can't authenticate" → check expiry, scopes, audit for revocation. Playbook: [identity-troubleshoot-guide.md → Playbook 5](references/identity-troubleshoot-guide.md#playbook-5--pat-or-external-app-not-working) - **Diagnose SMTP email delivery failures** — "invitations not sending", "SMTP broken" → smtp get + smtp test - **Investigate stuck tenant operations** — "tenant create not completing", "operation stuck" → poll operation status - **Identify service provisioning no-ops** — "service still enabled after remove" → platform-pinned services - **Triage robot account authentication issues** — "robot not authenticating" → identity vs credential model confusion > **Structured diagnose capability index** with failure-mode lookup and diagnostic priority ladder: [diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md). Quick investigation playbooks: [identity-troubleshoot-guide.md](references/identity-troubleshoot-guide.md). ## Critical Rules Each rule is the agent contract. Per-area detail is in the linked reference files. ### Universal 1. **Route Orchestrator-specific role/permission requests to `uip or roles`** (`uipath-platform` skill). `uip admin authorization` does NOT own Orchestrator's role catalog. **Conversely, all organization/tenant audit is owned HERE and served by `uip admin audit <scope>` (`sources` / `events` / `export`) — NEVER use `uip or audit-logs` for audit events, audit history, audit export, login history, compliance dumps, or "who did what/where" requests.** `uip or audit-logs` is a *different* surface (Orchestrator-operational audit — `Component,User,Action,Operation,Time` columns, `--export` returns a CSV; the `uipath-platform` skill). If you reach for `uip or audit-logs` on any org/tenant audit ask, stop and switch to `uip admin audit`. 2. **Verify login first.** `uip login status --output json`. If not logged in, stop and ask the user to run `uip login` — it opens an interactive browser flow, so never launch it yourself in an automated or non-interactive session (sessions authenticated via env vars are already logged in). Org id is resolved from the active session. 3. **Use `--output json` on every command.** Parse programmatically; present conversationally. 4. **Stop on error.** Show the error verbatim. Never retry auth failures — ask the user to `uip login`. 5. **Resolve every named principal before high-risk ops.** Any command that touches a named user / group / robot account / external app — `roles assignments create/delete`, `users delete`, `groups delete`, `groups members add/revoke`, `robot-accounts delete`, `external-apps delete`, `external-apps generate-secret` — MUST first search the directory and echo `Principal: <displayName> (<userName>) — <id>` back before the mutation runs. Zero matches → stop and ask; never fall back to the current login user. Multiple matches → numbered list, wait for a digit. Procedure: [role-assignment-management.md → Resolving Principal IDs](references/authorization/role-assignment-management.md#resolving-principal-ids). ### Identity 6. **Discover before creating.** `list` before `create` to avoid duplicates (robot accounts, groups, external apps — `users invite` excepted). 7. **Secrets shown only once** on external-app create and `generate-secret` — warn the user to save immediately. 8. **External apps require scopes at creation** — `--app-scope` or `--user-scope` is required (e.g., `--app-scope "OR.Folders"`). 9. **Group membership uses user IDs.** Resolve via `users list` per Rule 5, then `groups members add/revoke`. 10. **Confirm before delete** on users / groups / robot accounts / external apps — after resolving the named target per Rule 5. ### Authz 11. **Built-in roles are read-only.** Only `Custom` roles can be created / updated / deleted. CLI also rejects authoring against service-managed and platform-level services. Service lists: [role-management.md → Services That Manage Their Own Roles](references/authorization/role-management.md#services-that-manage-their-own-roles). 12. **`roles create` / `roles update` are PUT-style upserts.** Body is assembled from inline flags + `--file ./actions.json`. Always `roles get` first before updating — omitted flags overwrite that field. 13. **`--service` infers scope** (e.g., `--service studio` → `Tenant`; `--service apps` → `Organization`). Combine with `--scope` only to override. 14. **Listing works for every service; authoring is what's blocked.** `roles list --service <svc>` and `roles assignments list --service <svc>` accept every service. For effective access on a principal use `check-access` (PDP). 15. **Scope vocab differs across verbs.** `roles create --scope`: `Organization|TenantGlobal|Tenant|Project`. `roles assignments create --scope`: those + `Folder|App`. `roles assignments list --scope`: excludes `TenantGlobal`. `check-access --scope`: only `Tenant|Folder`. 16. **`roles assignments create/delete` MUST resolve the principal first** per Rule 5 — `--identity-id` is a raw UUID the CLI does not name-check. 17. **`roles assignments create` MUST match the role's `ownerServiceName` to the scope-path service segment.** `CentralizedAccess` → no service segment (`/` or `/tenant/<tid>`); anything else → path must include `lowercase(ownerServiceName)`. Display-name mapping (e.g., `Reinfer` → "IXP") + full procedure: [role-assignment-management.md → Validate Role's Owning Service](references/authorization/role-assignment-management.md#validate-roles-owning-service-vs-assignment-scope-path). ### OMS 18. **Async lifecycle: auto-poll, then hand off.** `tenants create/update/delete/enable/disable` return `operationId`. Auto-poll `organizations operation get <OP_ID>` 3× at 5 s; on terminal status stop and report; still in-progress after 3 polls → numbered menu, never indefinite loop. **`organizations create` and `organizations delete` are not exposed by the CLI** — Portal / support flow only. Procedure: [organization-management.md → Polling procedure](references/organization-management.md#polling-procedure-auto-poll-then-hand-off). 19. **`tenants delete` is soft-only.** No hard-delete flag; restoration is via support. 20. **Tenant commands default to the login tenant.** Always pass an explicit `<TENANT_ID>` for destructive ops (`tenants delete`, `tenants disable`, `tenants services remove`). 21. **Resolve region before tenant create.** `--region` is required on `tenants create` — run `organizations regions list` first. Tenant service catalog is region-aware. 22. **`services disable` / `remove` may no-op despite Success** on certain services. Always re-list after mutating. Gap list: [tenants-commands.md → Concepts](references/tenants-commands.md#concepts). ### Audit 23. **Disambiguate `org` vs `tenant` scope before querying.** If the prompt is vague AND no prior turn fixed the scope, **stop and ask once** (a single clarifying question — use AskUserQuestion when available) — never silently default to `tenant` or any single scope. If you genuinely cannot get an answer (non-interactive run) and must proceed, query **both** scopes and combine the results rather than guessing one — silently picking a single scope is the failure mode. **Scope is a positional subgroup, NOT a flag:** write `uip admin audit org sources` / `uip admin audit tenant events` — there is no `--scope` option (`audit sources --scope organization` is invalid). Routing table (user-phrasing → scope + why it lives where) and investigation playbooks: [audit-workflow-guide.md → Audit scope disambiguation](references/audit-workflow-guide.md#audit-scope-disambiguation--route-by-user-phrasing). 24. **`audit <scope> events` returns an object, not a bare array.** Shape is `{auditEvents, next, previous}`. Do not index `Data[0]`; read `Data.auditEvents[]`. **Cursor semantics are chronological**: `next` = newer events, `previous` = older events. The default newest-backward walk follows `previous`. 25. **`--limit` paginates internally — never loop on `--from-date` / `--to-date` to "paginate".** The server clamps `maxCount` to `[10, 200]` per request; when the user wants more than 200, the CLI fetches `ceil(N/200)` pages under the hood. Pass `--limit 500` (or larger, **up to the 10000 maximum**) — do NOT re-implement pagination in the agent. `--limit` must be in `[1, 10000]`; a bigger value is rejected up front with `Result: "ValidationError"`, so never pass an arbitrarily huge number to mean "everything" — for that, omit `--limit` or stay within the range. 26. **Discover via `audit <scope> sources` first — never invent source / target / type GUIDs.** The catalog response gives the GUIDs you pass to `events --source / --target / --type`. This is also the answer to "what audit events / sources can I see?" — **run `audit <scope> sources` and report the live catalog; do not answer conceptually from memory or the reference docs.** 27. **Bound the time window, ISO 8601 in UTC.** Don't call `audit <scope> events` without `--from-date` and `--to-date` on a noisy tenant. Accepted formats: date-only (`2026-04-01`) or with time (`2026-04-01T14:30:00Z`). **`--to-date` is inclusive of the exact instant** — to capture a full final day, pass the start of the next day or `T23:59:59.999Z`. This next-day trick is for `events` only — `export` bounds are whole days (Rule 30). Resolve relative phrases ("yesterday", "last 7 days") against the actual current UTC date (e.g. `date -u`) — never guess dates — and echo the resolved window in your reply. 27b. **"No matching event" is a complete answer — never name an actor the evidence does not support.** An audit trail is evidence, so attributing an action to the wrong person is worse than returning nothing. If the targeted query comes back empty, say so plainly, state what you searched (scope, source/target/type, window), and offer a next step (widen the window, try the other scope, check the resource ever existed). **Never** promote an actor from an adjacent event — a different resource, a different event type, or a broad `--search` hit — into the answer, and do not keep loosening filters until something returns and then present that as the culprit. Only name an actor when the cited event matches both the resource and the verb asked about, quoting `createdOn` plus the identifying `eventDetails` field so the user can verify it. Detail: [audit-workflow-guide.md → Step 5](references/audit-workflow-guide.md#step-5--when-nothing-matches-say-so). 28. **`--tenant-id` is silently ignored on `org`-scoped audit commands.** If you find yourself reaching for it on `audit org events`, switch to `audit tenant` instead.