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

package/skills/uipath-admin/references/diagnose/{references/failure-modes.md → failure-modes.md}

@@ -105,42 +105,102 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
 
 ---
 
-## User Gets HTTP 403 (Permission Denied)
+## Access Denied (HTTP 403)
 
-**Symptom:** User or integration receives 403 when calling a platform API or performing a UI action.
+**Symptom:** A principal — user, group member, robot account, or external app — receives 403 / "permission denied" from a platform API or a UI action. This is one investigation, not several. It covers "the user has no access," "the admin assigned a role and it isn't taking effect," and "the Orchestrator role doesn't work in Document Understanding."
 
-**Causes:**
-1. No role at all for the required service
-2. Role exists but at wrong scope (org vs tenant vs folder)
-3. Role missing the specific permission action
-4. Cross-service confusion (Orchestrator role ≠ DU access)
+**The diagnosis is a single comparison in two halves:** what the principal *effectively holds* (Step 1, from the PDP) against what the denied action *requires* (Step 2, from the catalog). Step 3 branches on which half of the comparison failed. Do not name a cause before both halves are in hand.
 
-**Investigation:**
-1. Resolve user: `uip admin users list --search "<USER_EMAIL>" --output json`
-2. Check effective access: `uip admin authorization check-access "<USER_ID>" --output json`
-3. Narrow to service: `uip admin authorization check-access "<USER_ID>" --service <SERVICE> --output json`
-4. Compare against required permission: `uip admin authorization permissions list --service <SERVICE> --output json`
-5. Label each result as `direct` or `inherited from <Group>` — see [check-access.md](../../authorization/check-access.md)
+### Step 1 — Establish what the principal effectively holds
 
-**Fix:** Cause 1 → assign a role for the service. Cause 2 → re-assign at correct scope. Cause 3 → update custom role actions or assign additional role. Cause 4 → assign role owned by the correct service.
+Resolve the principal first (Rule 5): `users list --search`, `groups list`, `robot-accounts list`, or `external-apps get`. If the principal does not exist, that is the root cause — stop.
 
----
+Then run the PDP. It is authoritative for effective permissions, including the server-side role catalogs that `roles assignments list` never returns:
 
-## Role Assignment Not Taking Effect
+```bash
+uip admin authorization check-access "<PRINCIPAL>" --output json
+uip admin authorization check-access "<PRINCIPAL>" --service <SERVICE> --output json
+```
 
-**Symptom:** Admin assigned a role but the principal still cannot perform the expected action.
+The principal is the positional argument (UUID, name, or email — there is no `--identity-id` on this command). `--scope` accepts only `Tenant` or `Folder`. Never pass `--service centralizedaccess`; omit `--service` for the umbrella view.
 
-**Causes:**
-1. `ownerServiceName` / scope-path mismatch (Rule 17) — most common
-2. Role assigned at wrong scope level (TenantGlobal vs Tenant vs Folder)
-3. Role missing the needed permission action
-4. Assignment at wrong tenant
+A permission reaches a principal by exactly two routes, and the fix differs by route. Label every nested `roleAssignments[]` entry; never collapse them:
 
-**Investigation:**
-1. Inspect the role first: `uip admin authorization roles get "<ROLE_ID>" --output json` — check `ownerServiceName` and `scopeType`
-2. Validate Rule 17: `CentralizedAccess` → no service segment in scope-path; any other value → path must include `lowercase(ownerServiceName)`
-3. Verify via PDP: `uip admin authorization check-access "<PRINCIPAL_ID>" --output json`
-4. List the principal's grants: `uip admin authorization roles assignments list --identity-id "<PRINCIPAL_ID>" --output json` (`--filter` is **not** a valid flag here — it exists on `roles list`, not on `assignments list`)
+| Nested entry | Route | Report as |
+|---|---|---|
+| `securityPrincipalType: "User"`, id == queried principal | Role assigned to the principal | `direct` |
+| `securityPrincipalType: "Group"` | Role assigned to a group the principal belongs to | `inherited from <Group>` |
+| `securityPrincipalType: "Robot"` / `"ExternalApplication"` | Role assigned to that non-user principal | `via <Robot\|ExternalApplication> <name>` |
+
+Repairing a direct grant targets the principal's own assignment; repairing an inherited grant requires changing group membership or the group's role binding. See [check-access.md](../authorization/check-access.md).
+
+Record four fields per granted role: role name, `ownerServiceName`, `scopeType`, and the scope path the grant sits at. Step 3 needs all four.
+
+### Step 2 — Establish what the denied action requires
+
+The PDP reports what the principal *has*; it never reports what the action *needs*. Look the required permission up in the catalog, searching the whole catalog rather than a guessed `--service` slice:
+
+```bash
+uip admin authorization permissions list --output json \
+  --output-filter "[?contains(Name, 'ADMINISTRATION')]"
+```
+
+`contains` is case-sensitive: `Name` is UPPERCASE, `Description` is lowercase. Three results that do **not** prove the permission is absent — never conclude "not found" from any of them:
+
+1. `Data: []` from a guessed `--service`.
+2. A truncated unfiltered list (the catalog is ~210 KB).
+3. A slice returning only the 10 cross-cutting `AUTHZ` rows — that floor signals a wrong `--service` / `--scope` pair, not an empty service.
+
+Narrow by role shape with `--scope`, never with a guessed `--service`. See [permission-catalog.md — Find the Permission Governing an Action](../authorization/permission-catalog.md#workflow-find-the-permission-governing-an-action).
+
+Read `ScopeType` from the hit. It fixes the role shape any fix must use (`TENANT` → a `Tenant`- or `TenantGlobal`-shape role).
+
+### Step 3 — Branch on the comparison
+
+| Step 1 vs Step 2 | Cause |
+|---|---|
+| No effective role carries the permission | [Cause A — the permission is not granted](#cause-a--the-permission-is-not-granted) |
+| A role carries the permission, but its grant sits at a scope path other than the one the denied call evaluates against | [Cause B — the permission is granted at the wrong scope](#cause-b--the-permission-is-granted-at-the-wrong-scope) |
+
+#### Cause A — The permission is not granted
+
+No role the principal effectively holds carries the permission from Step 2. Find which role does:
+
+```bash
+uip admin authorization roles list --service <SERVICE> --output json
+uip admin authorization roles get "<ROLE_ID>" --output json
+```
+
+`roles get` returns `ActionDetails[].Name`; match it against the permission name from Step 2. Use the permission's own owning service for `--service`, not a guess.
+
+State the diagnosis as: *principal holds `<roles>`, none of which carry `<PERMISSION.NAME>` (`ScopeType <SCOPE>`) → grant a `<SCOPE>`-shape role carrying it.* Never substitute a permission you did not find in Step 2.
+
+**Fix (Operate — present it, do not run it):** assign a role that carries the permission, directly or through a group the principal belongs to; or add the action to a custom role the principal already holds. `roles update` is a PUT-style upsert — run `roles get` first and resend the full action set (Rule 12). Built-in roles cannot be edited.
+
+#### Cause B — The permission is granted at the wrong scope
+
+The principal holds the permission and the PAP accepted the assignment; it simply never applies at the scope the denied call evaluates. Permissions are service-scoped and scope-path-bound: an Orchestrator role never grants Document Understanding, IXP, or any other service's access, whatever its actions say.
+
+Four shapes, most common first:
+
+| Shape | Example | Detect by |
+|---|---|---|
+| Wrong service segment | Denied call evaluates `/tenant/<tid>/documentunderstanding`; grant sits at `/tenant/<tid>/orchestrator` | Grant path's service segment ≠ the denied action's service |
+| Missing service segment (Rule 17 mismatch) | A `DocumentUnderstanding`-owned role granted at the bare `/tenant/<tid>` | `ownerServiceName` ≠ `CentralizedAccess` yet the path has no service segment |
+| Wrong scope level | A `Tenant` grant for a Folder- or Project-level action; an `Organization` role expected to cover a folder | Role `scopeType` ≠ the permission's `ScopeType` from Step 2 |
+| Wrong tenant | Grant on tenant A; the call runs on tenant B | Grant path's `<tid>` ≠ the failing tenant |
+
+Confirm a service split by running `check-access` with and without `--service <SERVICE>`: the missing service's permissions are absent from the filtered result while the umbrella view still shows the role.
+
+Validate the binding (Rule 17):
+
+1. `uip admin authorization roles get "<ROLE_ID>" --output json` — read `ownerServiceName` and `scopeType`.
+2. `CentralizedAccess` → the path carries **no** service segment (`/` for Organization, `/tenant/<tid>` for Tenant/TenantGlobal). Any other value → the path must contain `lowercase(ownerServiceName)`, e.g. `Reinfer` → `/tenant/<tid>/reinfer`. Display names (`Reinfer` → IXP, `DocumentUnderstanding` → Document Understanding) belong in prose only; echoed paths keep CLI slugs.
+3. Retrieve the grant and compare its actual path against the expected one:
+   ```bash
+   uip admin authorization roles assignments list --identity-id "<PRINCIPAL_ID>" --output json
+   ```
+   `--filter` is **not** a valid flag here — it exists on `roles list`, not on `assignments list`.
 
 > **A mis-scoped grant is invisible to the default listing — use `--scope-path` to see it.**
 > `assignments list` filters on a scope path **and** a service, both derived from your flags:
@@ -151,8 +211,8 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
 > | `--service <svc>` | `/tenant/<tid>/<svc>` | `<svc>` |
 > | `--scope-path <path>` (no `--service`) | `<path>` verbatim | **unset** |
 >
-> A Cause 1 grant — a `<svc>`-owned role granted at the bare `/tenant/<tid>` — matches
-> neither of the first two shapes: the centralized-access shapes exclude it on service,
+> A missing-service-segment grant — a `<svc>`-owned role granted at the bare `/tenant/<tid>` —
+> matches neither of the first two shapes: the centralized-access shapes exclude it on service,
 > and the `--service` shape excludes it on path. So it is absent from the default
 > listing, from `--identity-id`, from `--scope Tenant` (with or without
 > `--include-inherited`) and from `--service <svc>`. Retrieve it with the one shape that
@@ -167,23 +227,7 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
 > listing as "the grant does not exist"** — re-query with `--scope-path` first, and never
 > re-create the assignment on that basis, which reproduces the original mismatch.
 
-**Fix:** Cause 1 → re-create assignment with correct scope-path matching ownerServiceName. Cause 2 → re-assign at correct scope. Cause 3 → update role actions. Cause 4 → re-assign at correct tenant.
-
----
-
-## Cross-Service Permission Confusion
-
-**Symptom:** "I have a role in Orchestrator but can't access DU projects" or "CentralizedAccess role doesn't grant service-specific permissions."
-
-**Cause:** Permissions are service-scoped — an Orchestrator role does NOT grant DU, IXP, or other service access.
-
-**Investigation:**
-1. Check without service filter: `uip admin authorization check-access "<USER_ID>" --output json`
-2. Check with service filter: `uip admin authorization check-access "<USER_ID>" --service documentunderstanding --output json`
-3. Compare — the missing service's permissions will be absent
-4. Check role's `ownerServiceName` to confirm it belongs to the wrong service
-
-**Fix:** Assign a role owned by the correct service, or create a new custom role scoped to that service.
+**Fix (Operate — present it, do not run it):** re-create the assignment at the scope path that matches the role's `ownerServiceName` and the permission's `ScopeType`, using `--service <slug>` or an explicit `--scope-path`. Derive `<slug>` as `lowercase(ownerServiceName)` from this role's own `roles get`; never copy a service segment off another role's grant, and do not add a project segment for a `Tenant`-scope role. `Reinfer` (display name IXP) and `DocumentUnderstanding` are different services with different segments. Never widen a scope to make the call pass, and never coerce a path onto a role that does not own that service — if no role owns the intended service, author one under it. For folder-level access to Orchestrator resources, use Orchestrator's own folder roles (`uip or roles`, `uipath-platform`). See [role-assignment-management.md — Validate Role Service Binding and Scope Path](../authorization/role-assignment-management.md#validate-role-service-binding-and-scope-path).
 
 ---
 

package/skills/uipath-admin/references/diagnose/{references/troubleshooting-guide.md → troubleshooting-guide.md}

@@ -9,7 +9,7 @@ Determine which area the symptom belongs to based on user description:
 | Symptom | Domain | Next step |
 |---------|--------|-----------|
 | "Can't log in", auth error, login rejected | Identity — login | Step 2 (resolve user) |
-| "403", "permission denied", "access denied" | Authorization — access | Step 3 (check-access) |
+| "403", "permission denied", "access denied", "the role I was assigned isn't working", "my <service> role doesn't work in <other service>" | Authorization — access | Step 3, then [failure-modes → Access denied](failure-modes.md#access-denied-http-403) |
 | "Token not working", "PAT rejected" | Identity — PAT | Step 2 (resolve user), then [failure-modes → PAT rejected](failure-modes.md#pat-rejected) |
 | "OAuth failing", "client_credentials error" | Identity — external app | [failure-modes → OAuth2 failing](failure-modes.md#external-app-oauth2-flow-failing) |
 | "Robot not authenticating" | Identity — robot account | [failure-modes → Robot account](failure-modes.md#robot-account-not-authenticating) |
@@ -40,23 +40,19 @@ If the principal is not found → they were never provisioned or were deleted. T
 
 ## Step 3: Check Effective Access
 
-For any permission-related symptom (403, "can't do X", role not working), the PDP is the primary diagnostic tool:
+Every permission symptom — 403, "can't do X", "the role isn't taking effect", "my Orchestrator role doesn't work in DU" — is the **same** investigation: compare what the principal effectively holds against what the denied action requires. The PDP answers the first half and is the primary diagnostic tool:
 
 ```bash
-uip admin authorization check-access "<USER_ID>" --output json
-```
-
-To narrow to a specific service:
-```bash
-uip admin authorization check-access "<USER_ID>" --service orchestrator --output json
+uip admin authorization check-access "<PRINCIPAL>" --output json
+uip admin authorization check-access "<PRINCIPAL>" --service orchestrator --output json
 ```
 
 Interpret the results:
-- Label each role as `direct` or `inherited from <Group>` by inspecting `roleAssignments[].securityPrincipalType`
-- Compare effective permissions against the required permission for the denied action
-- Check `ownerServiceName` on each role — cross-service grants don't apply (Orchestrator role ≠ DU access)
+- A permission reaches a principal by exactly two routes. Label each nested `roleAssignments[]` entry `direct` (role assigned to the principal) or `inherited from <Group>` (role assigned to a group the principal belongs to) by inspecting `securityPrincipalType`. The fix differs by route.
+- Record role name, `ownerServiceName`, `scopeType`, and the grant's scope path for every granted role — the Step 3c branch needs all four.
+- Cross-service grants do not apply: an Orchestrator role is not DU access.
 
-See [check-access.md](../../authorization/check-access.md) for full interpretation guide.
+See [check-access.md](../authorization/check-access.md) for the full interpretation guide.
 
 ### Step 3b: Identify the Permission the Denied Action Requires
 
@@ -67,10 +63,21 @@ uip admin authorization permissions list --output json \
   --output-filter "[?contains(Name, 'ADMINISTRATION')]"
 ```
 
-`contains` is case-sensitive: `Name` is UPPERCASE, `Description` is lowercase. A guessed `--service` returns `Data: []` and an unfiltered list is ~210 KB that truncates — neither empty result proves the permission is absent. See [permission-catalog.md — Find the Permission Governing an Action](../../authorization/permission-catalog.md#workflow-find-the-permission-governing-an-action).
+`contains` is case-sensitive: `Name` is UPPERCASE, `Description` is lowercase. A guessed `--service` returns `Data: []`, an unfiltered list is ~210 KB that truncates, and a slice of only the 10 cross-cutting `AUTHZ` rows means the wrong slice — none of the three proves the permission is absent. Read `ScopeType` from the hit; it fixes the role shape any fix must use. See [permission-catalog.md — Find the Permission Governing an Action](../authorization/permission-catalog.md#workflow-find-the-permission-governing-an-action).
 
 State the diagnosis as: *principal holds `<roles>`, none of which carry `<PERMISSION.NAME>` (`ScopeType` `<SCOPE>`) → grant a `<SCOPE>`-shape role carrying it.* Never substitute a permission you did not find in the catalog.
 
+### Step 3c: Branch — Missing Permission or Wrong Scope
+
+With both halves in hand, exactly one of two causes holds. Follow the branch in [failure-modes → Access denied](failure-modes.md#step-3--branch-on-the-comparison):
+
+| Step 3 vs Step 3b | Cause |
+|---|---|
+| No effective role carries the permission | [The permission is not granted](failure-modes.md#cause-a--the-permission-is-not-granted) — find a role that carries it |
+| A role carries it, but the grant sits at another scope path | [The permission is granted at the wrong scope](failure-modes.md#cause-b--the-permission-is-granted-at-the-wrong-scope) — wrong or missing service segment, wrong scope level, or wrong tenant |
+
+A mis-scoped grant is **invisible** to the default `assignments list` shapes; never read an empty listing as "the grant does not exist" before re-querying with `--scope-path`.
+
 ## Step 4: Check Audit History
 
 For historical investigation (login failures, "who changed X", "when did access break"):
@@ -92,7 +99,7 @@ uip admin audit tenant events \
   --output json
 ```
 
-See [audit-workflow-guide.md](../../audit-workflow-guide.md) for scope routing rules.
+See [audit-workflow-guide.md](../audit-workflow-guide.md) for scope routing rules.
 
 ## Step 5: Inspect Configuration
 

package/skills/uipath-admin/references/external-app-management.md

@@ -1,30 +1,33 @@
 # External App Management
 
-Workflows for managing OAuth2 external clients via `uip admin external-apps`. For full command syntax and flags, see [identity-commands.md](identity-commands.md#external-apps--uip-admin-external-apps).
+Workflows for OAuth2 external clients via `uip admin external-apps`. See [identity-commands.md](identity-commands.md#external-apps--uip-admin-external-apps) for full syntax and flags.
 
-External apps provide Client ID + Secret credentials for API integrations, CI/CD pipelines, and external systems.
+External apps provide Client ID and Secret credentials for API integrations, CI/CD, and external systems. **They are not robot credentials.** See [Key Concepts — Robot Accounts vs External Apps](key-concepts.md#robot-accounts-vs-external-apps).
 
-> **External apps are NOT robot credentials.** See [SKILL.md — Robot Accounts vs External Apps](../SKILL.md#robot-accounts-vs-external-apps).
+## Scopes and Grant Types
 
-## Scope Types
+Run `uip admin scopes list --output json` to discover valid scopes.
 
-`--app-scope` grants permissions to the app itself (client_credentials flow). `--user-scope` delegates user permissions through the app (authorization_code flow). Discover available scopes: `uip admin scopes list --output json`
+- `--app-scope` grants app permissions for `client_credentials` (for example, `uip login --client-id`).
+- `--user-scope` delegates user permissions for the `authorization_code` browser flow.
+- Apps may have both, but each grant must use its matching scopes. Requesting user scopes through `client_credentials` fails with `not allowed to access User scopes`.
 
-## Workflow: Create a Confidential App (Server-Side)
+## Create an External App
 
-1. Check for duplicates: `uip admin external-apps list --output json`
-2. Create with app scopes:
+### Confidential app (server-side)
+
+1. Check for duplicates by running `uip admin external-apps list --output json`.
+2. Run:
    ```bash
    uip admin external-apps create "<APP_NAME>" \
      --app-scope "OR.Folders,OR.Assets,OR.Jobs" \
      --output json
    ```
-3. **Save the response immediately.** It contains `id` (Client ID) and `secret` (Client Secret — shown only once).
-
-## Workflow: Create a Public App (SPA/Mobile)
+3. Save the response immediately: `id` is the Client ID and `secret` is the Client Secret, shown only once.
 
-Non-confidential apps have no client secret. Require `--redirect-uri` and only support `--user-scope`. Do NOT use `--app-scope` with `--non-confidential` — the CLI will reject it. If user wants app-only scopes, create a confidential app (default) instead.
+### Public app (SPA/mobile)
 
+Run:
 ```bash
 uip admin external-apps create "<APP_NAME>" \
   --non-confidential \
@@ -33,8 +36,11 @@ uip admin external-apps create "<APP_NAME>" \
   --output json
 ```
 
-## Workflow: Create App with Both Scope Types
+Public apps have no client secret, require `--redirect-uri`, and support only `--user-scope`. Do not use `--app-scope` with `--non-confidential`; create a confidential app for app-only scopes.
+
+### App with both scope types
 
+Run:
 ```bash
 uip admin external-apps create "<APP_NAME>" \
   --app-scope "OR.Folders,OR.Jobs" \
@@ -43,25 +49,23 @@ uip admin external-apps create "<APP_NAME>" \
   --output json
 ```
 
-Apps with `--user-scope` require `--redirect-uri` for OAuth2 authorization code flow.
+Any app with `--user-scope` requires `--redirect-uri` for authorization-code flow.
 
-> **Scope types are tied to grant types.** `client_credentials` grant (non-interactive, e.g., `uip login --client-id`) can only access app scopes. `authorization_code` grant (interactive browser flow) can only access user scopes. An app with both scope types registered works — but each grant type can only use its matching scopes. Requesting user scopes via client_credentials will fail with "not allowed to access User scopes".
+## Secrets
 
-## Workflow: Generate/Delete Secrets
-
-Generate (value shown only once):
+Run the following to generate a secret; its value is shown only once:
 ```bash
 uip admin external-apps generate-secret <CLIENT_ID> --description "Rotated secret" --expiration "2027-06-01" --output json
 ```
 
-Delete (only secret ID needed — confirm with user first):
+Confirm with the user first, then run the following to delete a secret; only the secret ID is required:
 ```bash
 uip admin external-apps delete-secret <SECRET_ID> --output json
 ```
 
-## Workflow: Update an External App
+## Update an External App
 
-At least one field required. Scopes are **replaced, not merged** — provide complete list.
+Provide at least one update flag. Scopes are replaced, not merged; provide the complete list.
 
 ```bash
 uip admin external-apps update <CLIENT_ID> \
@@ -70,19 +74,20 @@ uip admin external-apps update <CLIENT_ID> \
   --output json
 ```
 
-## Workflow: Delete an External App
+Valid update fields are `--name`, `--app-scope`, `--user-scope`, and `--redirect-uri`.
 
-Confirm with user first — this revokes all secrets and access.
+## Delete an External App
 
+Confirm with the user first; deletion revokes all secrets and access. Then run:
 ```bash
 uip admin external-apps delete <CLIENT_ID> --output json
 ```
 
 ## Federated Credentials
 
-Enable workload identity federation with external identity providers (GitHub Actions, Azure AD) — authenticate without client secrets.
+Use workload identity federation with external identity providers such as GitHub Actions or Azure AD to authenticate without client secrets.
 
-### Create a Federated Credential
+### Create
 
 ```bash
 uip admin external-apps federated-credentials create <CLIENT_ID> \
@@ -93,15 +98,15 @@ uip admin external-apps federated-credentials create <CLIENT_ID> \
   --output json
 ```
 
-### List Federated Credentials
+### List
 
 ```bash
 uip admin external-apps federated-credentials list <CLIENT_ID> --output json
 ```
 
-### Update a Federated Credential
+### Update
 
-All fields are required on update (full replace):
+All fields are required; updates are full replacements.
 
 ```bash
 uip admin external-apps federated-credentials update <CLIENT_ID> <CREDENTIAL_ID> \
@@ -112,31 +117,29 @@ uip admin external-apps federated-credentials update <CLIENT_ID> <CREDENTIAL_ID>
   --output json
 ```
 
-### Delete a Federated Credential
-
-Confirm with user before deleting.
+### Delete
 
+Confirm with the user first, then run:
 ```bash
 uip admin external-apps federated-credentials delete <CLIENT_ID> <CREDENTIAL_ID> --output json
 ```
 
-## Using Credentials for Authentication
-
-After creating an external app, use Client ID and Secret for non-interactive login:
+## Authenticate with an External App
 
+Run this for non-interactive login:
 ```bash
 uip login --client-id "<CLIENT_ID>" --client-secret "<CLIENT_SECRET>" --tenant "<TENANT_NAME>" --output json
 ```
 
-Used by: CI/CD pipelines, external API integrations, service-to-service calls, automated scripts.
+Use it for CI/CD pipelines, external API integrations, service-to-service calls, and automated scripts.
 
 ## Error Handling
 
 | Error | Cause | Fix |
-|-------|-------|-----|
+|---|---|---|
 | `already exists` | App name taken | Choose a unique name |
 | `No fields to update` | No update flags provided | Provide `--name`, `--app-scope`, `--user-scope`, or `--redirect-uri` |
-| `not found` | Invalid client ID | Run `external-apps list` to find correct ID |
+| `not found` | Invalid client ID | Run `external-apps list` to find the correct ID |
 | `scope not found` | Invalid scope name | Run `uip admin scopes list` to find valid scopes |
-| Non-confidential + `--app-scope` | Public apps can't use app scopes | Use `--user-scope` only |
-| User scopes without redirect URI | OAuth2 auth code flow needs redirect | Add `--redirect-uri` |
+| Non-confidential + `--app-scope` | Public apps cannot use app scopes | Use `--user-scope` only |
+| User scopes without redirect URI | Authorization-code flow requires redirect | Add `--redirect-uri` |