@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-admin/references/identity-troubleshoot-guide.md

@@ -1,100 +1,112 @@
 # Identity & Authorization Troubleshooting Guide
 
-Common investigation playbooks for identity, access, and security issues. Each starts from a user-reported symptom and resolves to a diagnosis using `uip admin` commands.
+Investigation playbooks for identity, access, and security issues using `uip admin` commands.
 
 > Every command assumes the user has run `uip login`. Every command uses `--output json`.
 
 ---
 
-## Playbook 1 — "User can't access resource X"
+## Playbook 1 — "Access denied (HTTP 403)"
 
-**Symptom:** "Alice can't publish to the Finance folder" / "Bob gets 403 on the API" / "The new contractor has no access to anything"
+**Symptoms:** A user cannot publish, receives a 403, has no access, or was assigned a role that appears to do nothing. These are one scenario, not several.
 
-**Root causes (most → least common):**
-1. Missing role assignment at the correct scope
-2. Role exists but lacks the specific permission
-3. User not in the expected group
-4. User account disabled or not yet activated
+**Root causes (most → least common):** the principal holds no role carrying the required permission; the permission is granted but at the wrong scope path (wrong or missing service segment, wrong scope level, wrong tenant); the user is not in the expected group; the user is disabled or not activated.
 
-### Step 1 — Resolve the principal
+The canonical branch — missing permission versus mis-scoped grant — is [diagnose/failure-modes.md → Access denied](diagnose/failure-modes.md#access-denied-http-403). Steps 1 and 3 below are the identity-side checks that come first.
+
+### Step 1 — Resolve the principal and confirm it is active
+
+Run:
 
 ```bash
 uip admin users list --search "<EMAIL_OR_NAME>" --output json
 ```
 
-Extract the user's `id` (GUID) and `isActive` status. If `isActive` is `false`, the user is deactivated — that's the diagnosis. Otherwise proceed.
+Extract `id` (GUID) and `isActive`. If `isActive` is `false`, the user is deactivated; that is the root cause — stop.
 
 ### Step 2 — Check effective access
 
+Run:
+
 ```bash
 uip admin authorization check-access <USER_GUID> --scope Tenant --output json
 ```
 
-Or for folder-level:
+For folder-level access, run:
 
 ```bash
 uip admin authorization check-access <USER_GUID> --scope Folder --folder-id <FOLDER_UUID> --output json
 ```
 
-Inspect `Data.roleAssignments[]` — each entry shows `roleName`, `scopeType`, and `securityPrincipalType` (`direct` = assigned to the user; `inherited` or `Group` = inherited from a group). Look for whether the needed permission (e.g., `Publish`) appears anywhere. If absent, that's the gap.
-
-### Step 3 — List current role assignments
-
-```bash
-uip admin authorization roles assignments list --identity-id <USER_GUID> --output json
-```
+Inspect `Data.roleAssignments[]`. Label every nested entry by `securityPrincipalType`: `User` with the queried id is a **direct** grant; `Group` is **inherited** through group membership. Record `roleName`, `ownerServiceName`, `scopeType`, and the grant's scope path for each granted role.
 
-Compare the user's assignments against what's needed. Check `ownerServiceName` and `scopeType` — a role scoped to `Organization` won't grant folder-level permissions.
+### Step 3 — Check group membership
 
-### Step 4 — Check group membership
+When access is expected to arrive through a group, run:
 
 ```bash
 uip admin groups list --output json
 ```
 
-For each relevant group, check if the user is a member. If the user should inherit permissions via a group but isn't in it, that's the gap:
+For each relevant group, run:
 
 ```bash
 uip admin groups members list <GROUP_ID> --output json
 ```
 
+If the user is absent from the group that carries the role, the gap is membership — not the role or its scope.
+
+### Step 4 — Branch: missing permission, or right permission at the wrong scope
+
+Look up the permission the denied action requires ([permission-catalog.md](authorization/permission-catalog.md#workflow-find-the-permission-governing-an-action)), then take the branch:
+
+- **No effective role carries it** → [Cause A](diagnose/failure-modes.md#cause-a--the-permission-is-not-granted). Find a role that does with `roles list --service <SERVICE>` and `roles get <ROLE_ID>` (compare `ActionDetails[].Name`). To extend a custom role instead, re-fetch first and send the full action set — `roles update` is a PUT-style upsert (Rule 12).
+- **A role carries it but the grant sits elsewhere** → [Cause B](diagnose/failure-modes.md#cause-b--the-permission-is-granted-at-the-wrong-scope). Verify `ownerServiceName` against the scope-path service segment (Rule 17). A `Tenant` role cannot provide folder-level access: use a `Project`-scoped role, or Orchestrator's own folder roles (`uip or roles`, `uipath-platform`).
+
 ### Step 5 — Diagnose and recommend
 
-Present findings as:
+Report:
 - **Principal:** `<displayName> (<email>) — <id>`
-- **Current access:** list of roles + scopes
-- **Missing:** specific role or permission needed
-- **Fix:** "Assign role X at scope Y" or "Add user to group Z"
+- **Current access:** roles, scopes, and whether each is direct or inherited
+- **Missing:** the required permission, or the scope path the existing grant should sit at
+- **Fix:** "Assign role X at scope Y", "Add user to group Z", or "Re-create the assignment at `<path>`" — present it; do not execute it
 
 ---
 
 ## Playbook 2 — "Suspicious login activity"
 
-**Symptom:** "Failed login attempts" / "Account may be compromised" / "Unknown logins from strange locations"
+**Symptoms:** Failed logins, possible compromise, or unknown locations.
 
-**Scope: `org`.** Login events (User Login, Robot Login, External App Login) are org-level audit events under Identity → Authentication.
+**Scope: `org`.** User Login, Robot Login, and External App Login events are org-level audit events under Identity → Authentication.
 
 ### Step 1 — Resolve the user
 
+Run:
+
 ```bash
 uip admin users list --search "<EMAIL>" --output json
 ```
 
-Extract the `id` for `--user-id` filtering.
+Extract `id` for `--user-id`.
 
 ### Step 2 — Discover login event types
 
+Run:
+
 ```bash
 uip admin audit org sources --output json > /tmp/sources.json
 ```
 
-Extract the User Login type GUID:
+Extract the User Login type GUID by running:
+
 ```bash
 jq -r '.Data[] | select(.name == "Identity") | .eventTargets[] | select(.name == "Authentication") | .eventTypes[] | select(.name == "User Login") | .id' /tmp/sources.json
 ```
 
 ### Step 3 — Query login events
 
+Run:
+
 ```bash
 uip admin audit org events \
   --user-id <USER_GUID> \
@@ -107,131 +119,97 @@ uip admin audit org events \
 
 ### Step 4 — Analyze
 
-For each event in `Data.auditEvents[]`, check:
-- `status` — `0` = Success, `1` = Failure
-- `clientInfo` — parse JSON string for `ipAddress` and `ipCountry`
-- `createdOn` — timestamp (UTC)
-
-Flag: multiple failures from different IPs, logins from unexpected countries, or logins outside business hours.
+For each `Data.auditEvents[]`, check `status` (`0` = Success, `1` = Failure), parse the `clientInfo` JSON string for `ipAddress` and `ipCountry`, and use `createdOn` as the UTC timestamp. Flag multiple failures from different IPs, unexpected countries, or logins outside business hours.
 
 ---
 
-## Playbook 3 — "Role misconfiguration"
-
-**Symptom:** "Custom role doesn't grant what it should" / "User has a role but still can't do X"
+## Playbook 3 — "IP restriction lockout"
 
-### Step 1 — Inspect the role
-
-```bash
-uip admin authorization roles list --output json
-```
-
-Find the role by name, then:
-
-```bash
-uip admin authorization roles get <ROLE_ID> --output json
-```
-
-Check `actions[]` — these are the permission strings (e.g., `OR.Folders.Create`). Compare against the Permission Catalog:
-
-```bash
-uip admin authorization permissions list --service <SERVICE> --output json
-```
-
-### Step 2 — Verify scope alignment
-
-The role's `scopeType` (Organization / TenantGlobal / Tenant / Project) must match the assignment scope. A role scoped to `Organization` cannot be assigned at `Folder` scope. Check the assignment:
-
-```bash
-uip admin authorization roles assignments list --identity-id <USER_GUID> --output json
-```
-
-Verify `ownerServiceName` matches the scope-path service segment (Rule 17 from SKILL.md).
-
-### Step 3 — Diagnose
-
-Common misconfigurations:
-- **Scope mismatch:** role is `Tenant` but user needs folder-level access → create a `Project`-scoped role or use Orchestrator folder roles instead (`uip or roles`)
-- **Missing actions:** role omits required permissions → `roles update` with the full action set (re-fetch first — Rule 12)
-- **Wrong service:** role's `ownerServiceName` doesn't match the target service
-
----
-
-## Playbook 4 — "IP restriction lockout"
-
-**Symptom:** "Can't access the platform from new office" / "All users blocked" / "IP restriction locked us out"
+**Symptoms:** Access fails from a new office or all users are blocked.
 
 ### Step 1 — Check enforcement status
 
+Run:
+
 ```bash
 uip admin ip-restriction enforcement get --output json
 ```
 
-If `isEnabled` is `false`, IP restriction is not the cause — look elsewhere.
+If `isEnabled` is `false`, investigate another cause.
 
 ### Step 2 — Check caller's IP
 
+Run:
+
 ```bash
 uip admin ip-restriction my-ip --output json
 ```
 
-Returns `Data.ipAddress` — the public IP the platform sees for the caller.
+Use `Data.ipAddress` as the public IP seen by the platform.
 
 ### Step 3 — List allowed ranges
 
+Run:
+
 ```bash
 uip admin ip-restriction ip-ranges list --output json
 ```
 
-Compare the caller's IP against every entry's CIDR range. If the IP is not covered by any entry, that's the lockout cause.
+Compare the caller's IP with every entry's CIDR range. If none covers it, identify that as the lockout cause.
 
 ### Step 4 — Check bypass rules
 
+Run:
+
 ```bash
 uip admin ip-restriction bypass-rules list --output json
 ```
 
-Bypass rules exempt specific URL patterns from IP restriction. If the affected access is via an API endpoint matching a bypass pattern, the IP restriction should not apply — investigate other causes.
+Bypass rules exempt matching URL patterns. If the affected API endpoint matches one, investigate another cause.
 
 ### Step 5 — Resolution options
 
-- **Add the new IP/CIDR:** `ip-ranges create --name "<LOCATION>" --cidr <CIDR> --output json`
-- **Disable enforcement temporarily:** `ip-restriction enforcement disable --output json` (if accessible from an allowed IP)
-- **Platform recovery:** if fully locked out, use the Portal recovery flow (no CLI bypass exists — Rule 32)
+- Add the IP/CIDR by running: `ip-ranges create --name "<LOCATION>" --cidr <CIDR> --output json`
+- Temporarily disable enforcement by running: `ip-restriction enforcement disable --output json` (if accessible from an allowed IP)
+- If fully locked out, use the Portal recovery flow; no CLI bypass exists (Rule 32).
 
 ---
 
-## Playbook 5 — "PAT or external app not working"
+## Playbook 4 — "PAT or external app not working"
 
-**Symptom:** "API calls return 401" / "PAT stopped working" / "External app can't authenticate"
+**Symptoms:** API calls return 401, a PAT stopped working, or an external app cannot authenticate.
 
 ### Step 1 — List PATs or external apps
 
-For PATs:
+For PATs, run:
+
 ```bash
 uip admin pat list --output json
 ```
 
-Check `expiration` — expired PATs return 401 silently. If the token is absent from the list, it was revoked (revocation is a hard delete — no `isRevoked` flag exists).
+Check `expiration`; expired PATs return 401 silently. If a token is absent, it was revoked; revocation is a hard delete and has no `isRevoked` flag.
+
+For external apps, run:
 
-For external apps:
 ```bash
 uip admin external-apps list --output json
 ```
 
 ### Step 2 — Verify scopes
 
-PATs and external apps are scoped — if the API call requires `OR.Execution` but the token only has `OR.Folders.Read`, the call fails.
-
-For external apps, check the declared scopes against the API endpoint's requirement. For PATs, re-create with the correct `--scope`.
+Compare token or app scopes with the endpoint requirement. For example, an endpoint requiring `OR.Execution` fails when the token has only `OR.Folders.Read`. Re-create a PAT with the correct `--scope`.
 
 ### Step 3 — Check audit for revocation
 
-Query org audit for recent identity events — a PAT or app secret may have been revoked:
+Discover sources by running:
 
 ```bash
 uip admin audit org sources --output json
-# Find Identity source → PersonalAccessTokens or ExternalApps target
+```
+
+Find the Identity source → PersonalAccessTokens or ExternalApps target, then query recent events by running:
+
+```bash
 uip admin audit org events \
   --source <IDENTITY_SOURCE_GUID> \
   --from-date <RECENT_WINDOW> \

package/skills/uipath-admin/references/ip-restriction/bypass-rule-management.md

@@ -1,80 +1,51 @@
 # Bypass Rule Management
 
-Multi-step workflows for managing URL-pattern bypass rules via `uip admin ip-restriction bypass-rules`. For per-command flag tables, output codes, and single-command examples, see [ip-restriction-commands.md](ip-restriction-commands.md).
+Manage URL-pattern bypass rules with `uip admin ip-restriction bypass-rules`. See [ip-restriction-commands.md](ip-restriction-commands.md) for per-command flag tables, output codes, and single-command examples.
 
 ## Concept
 
-Bypass rules carve out **URL-pattern exceptions** to IP allowlisting. Use them when the org has enforcement on but needs a specific App / folder / tenant URL pattern to remain reachable from outside the allowed IP ranges.
+Bypass rules create **URL-pattern exceptions** to IP allowlisting for specific App, folder, or tenant URL patterns. The server compiles each `regexEntry`; optional metadata may include `appName` and tenant association. Rules have no effect when [enforcement](enforcement-management.md) is `Disabled`.
 
-Each rule's regex pattern (`regexEntry`) is compiled server-side from the supplied string. Optional metadata (`appName`, tenant association) can travel with the rule.
+## Inspect
 
-Bypass rules only matter when [enforcement](enforcement-management.md) is `Enabled`. When enforcement is `Disabled`, they have no effect.
+Before creating, updating, or deleting a rule, run:
 
-## Workflow: List & Inspect Rules
+- `uip admin ip-restriction bypass-rules list --output json` to list all rules.
+- `uip admin ip-restriction bypass-rules list --filter "<FRAGMENT>" --output json` for a case-insensitive substring search across `regexEntry` and `appName`.
+- `uip admin ip-restriction bypass-rules get <RULE_ID> --output json` to inspect one rule, including `regexEntry`, `appName`, tenant association, and timestamps.
 
-Use these read patterns before any create / update / delete to confirm what's already in place.
+Use inspection to confirm the target before update or delete.
 
-### List all rules
+## Create
 
-```bash
-uip admin ip-restriction bypass-rules list --output json
-```
+Create is file-only; there is no inline shortcut for the create body.
 
-### Search by pattern fragment or app name
-
-`--filter` runs a case-insensitive substring match on each rule's `regexEntry` *and* `appName`. Useful when you remember a domain fragment but not the rule id.
-
-```bash
-uip admin ip-restriction bypass-rules list --filter "<FRAGMENT>" --output json
-```
-
-### Inspect one rule by id
-
-```bash
-uip admin ip-restriction bypass-rules get <RULE_ID> --output json
-```
-
-Returns `regexEntry`, `appName`, tenant association, and timestamps. Use this before update/delete to confirm you're targeting the right rule.
-
-## Workflow: Create a Bypass Rule
-
-Create is file-only (no inline shortcut for the create body).
-
-1. Author the rule body (`bypass-rule.json`):
+1. Write `bypass-rule.json`, for example:
    ```json
    {
      "regexEntry": "^.*\\.contoso\\.com$",
      "appName": "<OPTIONAL_APP_NAME>"
    }
    ```
-   Refer to UiPath docs for the full `AddRegexBypassRequest` schema (tenant fields, etc.).
-2. Create:
-   ```bash
-   uip admin ip-restriction bypass-rules create --file ./bypass-rule.json --output json
-   ```
-3. Verify:
-   ```bash
-   uip admin ip-restriction bypass-rules get <NEW_RULE_ID> --output json
-   ```
+   Refer to UiPath docs for the full `AddRegexBypassRequest` schema, including tenant fields.
+2. Run `uip admin ip-restriction bypass-rules create --file ./bypass-rule.json --output json`.
+3. Run `uip admin ip-restriction bypass-rules get <NEW_RULE_ID> --output json` to verify the result.
 
-## Authoring Tips
+## Authoring Rules
 
-- **Escape dots in regex.** A pattern like `.contoso.com` matches `Xcontoso.com` too. Use `\.contoso\.com`.
-- **Anchor with `^` and `$`.** Otherwise the pattern matches any URL containing the fragment.
-- **Test before deploying broadly.** Add the rule, verify it via UiPath app access, then promote.
+- Escape dots: `.contoso.com` also matches `Xcontoso.com`; use `\\.contoso\\.com`.
+- Anchor patterns with `^` and `$` to avoid matching URLs containing the fragment.
+- Test the rule through UiPath app access before deploying it broadly.
 
-## Workflow: Update a Rule
+## Update
 
-- **Regex-only change** — pass `--regex-entry "<NEW_PATTERN>"` inline.
-- **Tenant / app metadata** — pass `--file ./bypass-rule-update.json` with the full `UpdateRegexBypassRequest` body.
+- For a regex-only change, pass `--regex-entry "<NEW_PATTERN>"` inline.
+- For tenant or app metadata, pass `--file ./bypass-rule-update.json` containing the full `UpdateRegexBypassRequest` body.
 
-## Workflow: Delete a Rule
+## Delete
 
-1. Confirm the rule to delete:
-   ```bash
-   uip admin ip-restriction bypass-rules get <RULE_ID> --output json
-   ```
-2. Confirm with the user.
+1. Run `uip admin ip-restriction bypass-rules get <RULE_ID> --output json` and confirm the target.
+2. Confirm the deletion with the user.
 3. Run `bypass-rules delete <RULE_ID>`.
 
-No `--confirm` flag required (unlike `ip-ranges delete`) — bypass-rule deletion only narrows access, never widens it.
+Do not use a `--confirm` flag: unlike `ip-ranges delete`, bypass-rule deletion only narrows access and never widens it.

package/skills/uipath-admin/references/ip-restriction/enforcement-management.md

@@ -1,43 +1,36 @@
 # Enforcement Management
 
-Multi-step workflows for the org-wide IP-restriction enforcement switch (`uip admin ip-restriction enforcement`) and the `my-ip` lookup that supports it. For per-command flag tables, output codes, and single-command examples, see [ip-restriction-commands.md](ip-restriction-commands.md).
+Manage the organization-wide IP-restriction enforcement switch (`uip admin ip-restriction enforcement`) and `my-ip` lookup. See [ip-restriction-commands.md](ip-restriction-commands.md) for per-command flags, output codes, and single-command examples.
 
 ## Concept
 
-`enforcement` is a singleton switch per organization:
+`enforcement` is a per-organization singleton switch:
 
-- **Disabled** (default) — platform default access rules apply; `ip-ranges list` is just data, no enforcement.
-- **Enabled** — only IP networks in `ip-ranges list` can reach this org. Everything else is blocked.
+- **Disabled** (default): platform-default access rules apply; `ip-ranges list` is data only.
+- **Enabled**: only networks in `ip-ranges list` can reach the organization.
 
-Toggling the switch is **idempotent** on both sides — flipping twice is a safe no-op.
-
-**Lockout risk is real.** Enabling enforcement with the caller's IP outside the allowlist locks the caller out (and possibly the whole org). The CLI has two safety rails:
-
-1. `enforcement enable` runs a `my-ip` pre-flight and **rejects** the call if the caller's IP is not covered by any entry in `ip-ranges list`.
-2. `--confirm` is required to acknowledge the lockout risk.
+Toggling is idempotent. Enabling can lock out callers whose IP is not allowlisted, so the CLI requires `--confirm` and performs a `my-ip` pre-flight.
 
 ## Workflow: Pre-Flight Before Enabling Enforcement
 
-Before flipping `enforcement enable`, confirm the caller's IP is in the allowlist. The CLI runs the same check server-side and will reject otherwise — front-loading it lets you fix the allowlist explicitly instead of guessing from a rejected call.
-
-1. Check current state:
+1. Run:
    ```bash
    uip admin ip-restriction enforcement get --output json
    ```
-2. Look up the caller's public IP:
+2. Run:
    ```bash
    uip admin ip-restriction my-ip --output json
    ```
-3. List allowlist entries and verify the IP is covered:
+3. Run:
    ```bash
    uip admin ip-restriction ip-ranges list --output json
    ```
-   Compare `my-ip`'s `ipAddress` against each entry's `ipNetwork` CIDR. If no entry covers your IP, add one before enabling — see [ip-range-management.md — Workflow: Add an Entry](ip-range-management.md#workflow-add-an-entry-idempotent-on-cidr).
+   Compare `my-ip`'s `ipAddress` with every entry's `ipNetwork` CIDR. If none covers the caller's IP, add one before enabling; see [ip-range-management.md — Workflow: Add an Entry](ip-range-management.md#add-an-entry-idempotent-on-cidr).
 
 ## Workflow: Enable Enforcement
 
-1. Run the pre-flight above.
-2. **State the impact and prompt for an explicit confirmation.** Do not run `enforcement enable` until the user has acknowledged the impact in this turn. Render verbatim:
+1. Complete the pre-flight.
+2. State the impact and obtain explicit confirmation in this turn. Render verbatim:
 
    ```
    ⚠️ About to enable IP Restriction for this organization.
@@ -57,30 +50,25 @@ Before flipping `enforcement enable`, confirm the caller's IP is in the allowlis
    Proceed?  (yes / no)
    ```
 
-   On "no" → stop. On "yes" → run the command. **Never substitute the prompt with a one-line "are you sure".** The full impact statement is required because of the lockout severity.
-
-3. Enable:
+   On `no`, stop. On `yes`, continue. Never replace this prompt with a one-line confirmation.
+3. Run:
    ```bash
    uip admin ip-restriction enforcement enable --confirm --output json
    ```
-
-The CLI runs its own `my-ip` pre-flight and rejects the call if the caller is not covered. If rejected, do NOT retry until the allowlist is fixed.
-
-4. **Post-state check.** Re-run `enforcement get` and `my-ip` immediately after. If the caller's IP is still covered, report success. If something looks off, instruct the user to use the recovery flow before they lose access.
+   The CLI runs its own `my-ip` pre-flight and rejects enablement when the caller is not covered. If rejected, do not retry until the allowlist is fixed.
+4. Immediately run `enforcement get` and `my-ip` again. Report success only if the caller's IP remains covered. If anything looks wrong, instruct the user to use the recovery flow before access is lost.
 
 ## Workflow: Disable Enforcement
 
-Safe and idempotent — restores platform default access:
+Run:
 
 ```bash
 uip admin ip-restriction enforcement disable --output json
 ```
 
-No `--confirm` required. Use to recover from a near-lockout, or to bypass the `ip-ranges delete` safety pre-flight.
+Disabling is safe and idempotent, restores platform-default access, requires no `--confirm`, and can recover a near-lockout or bypass the `ip-ranges delete` safety pre-flight.
 
 ## Recovery from Lockout
 
-If `enforcement enable` succeeded but a subsequent change locked the caller out:
-
-1. Access UiPath from an IP already in the allowlist (e.g., a different VPN or office network), then run `enforcement disable`.
-2. If no such IP is available, the org owner must use the UiPath Portal lockout-recovery flow or contact support — there is no CLI bypass.
+1. Access UiPath from an IP already in the allowlist, such as another VPN or office network, then run `enforcement disable`.
+2. If no such IP is available, have the organization owner use the UiPath Portal lockout-recovery flow or contact support. There is no CLI bypass.