Add PingCastle 4.0 Swagger API documentation

[JoeDibley]

Summary

• New page enterpriseapiswagger.md covering the full Swagger walkthrough for PingCastle Enterprise: prerequisites (IIS anonymous auth, base URL/Agent API key), opening Swagger, authenticating, token expiry, troubleshooting 401s, F12 dev tools, and calling the API from PowerShell.
• Added to the User Guide sidebar; cross-linked from enterpriseagentdeployment.md, index.md, and the existing 401 KB article.

Test plan

• DOCS_PRODUCT=pingcastle npm run build succeeds, no broken links for pingcastle pages
• Dev server: new page loads (200) at /docs/pingcastle/4_0/enterpriseapiswagger
• Dale linter run against new file — no violations
• PowerShell code blocks carried over verbatim, fenced as powershell

[github-actions]

⚠️ Broken Anchor Links

2 broken anchor link(s) found — these will cause the build to fail.

  docs/pingcastle/4.0/enterpriseapiswagger.md:106
    For a full walkthrough of the 401/IIS root cause, see [Scheduler or Agent Deployment Returns 401 Unauthorized Error](kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md).
    docs/pingcastle/4.0/kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md not found
  docs/pingcastle/4.0/enterpriseapiswagger.md:294
    - [Scheduler or Agent Deployment Returns 401 Unauthorized Error](kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md)
    docs/pingcastle/4.0/kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md not found

Auto-Fix Summary

18 issues fixed, 11 skipped across 3 files

Category	Fixes
Dale: misplaced-modifiers	1
Dale: passive-voice	11
Dale: wordiness	5
Dale: xy-slop	1

Skipped (needs manual review)	Reason

| docs/pingcastle/4.0/index.md:17 — Dale: passive-voice | "The source code of the program is licensed to the Non-Profit OSL 3.0" is a legal license statement; an active rewrite risks changing its legal meaning |
| docs/pingcastle/4.0/index.md:542 — Dale: passive-voice | "determine if patches have been applied" has no faithful active rewrite — the agent is genuinely unspecified and alternatives shift the meaning |
| docs/pingcastle/4.0/index.md:729 — Dale: passive-voice | "can also be misused by attackers" sits inside the quoted Netwrix security statement blockquote; editing verbatim quoted text isn't appropriate |
| docs/pingcastle/4.0/index.md:736 — Dale: passive-voice | "No malicious payloads or hidden behavior are present in the software" is inside the same quoted security statement |
| docs/pingcastle/4.0/index.md:738 — Dale: idioms | "In short" appears inside the quoted security statement blockquote |
| docs/pingcastle/4.0/index.md:270 — Dale: passive-voice | "XML reports generated from multiple locations" is a reduced relative clause reading as an adjective; rewriting adds no clarity |
| docs/pingcastle/4.0/index.md:298 — Dale: passive-voice | "cartography reports run from multiple locations" reads adjectivally; an active rewrite would be more awkward than the original |
| docs/pingcastle/4.0/index.md:206 — Dale: wordiness | "Risks associated with trust relationships" is a table cell where the longer phrasing keeps the category description parallel with the others |
| docs/pingcastle/4.0/index.md:210 — Dale: wordiness | "Clicking on a rule reveals..." could become an imperative, but the sentence is descriptive rather than a procedure step and the rewrite changes its role |
| docs/pingcastle/4.0/index.md:9 — Dale: undefined-acronyms | CISO is standard industry vocabulary for this audience, excluded by the rule |
| docs/pingcastle/4.0/enterpriseagentdeployment.md:38 — Dale: minimizing-difficulty | "you can simplify scan configuration by using automatic forest exploration" describes a real capability of the feature rather than minimizing the reader's effort |

Ask @claude on this PR if you'd like an explanation of any fix.

[github-actions]

⚠️ Broken Anchor Links

2 broken anchor link(s) found — these will cause the build to fail.

  docs/pingcastle/4.0/enterpriseapiswagger.md:106
    For a full walkthrough of the 401/IIS root cause, see [Scheduler or Agent Deployment Returns 401 Unauthorized Error](kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md).
    docs/pingcastle/4.0/kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md not found
  docs/pingcastle/4.0/enterpriseapiswagger.md:294
    - [Scheduler or Agent Deployment Returns 401 Unauthorized Error](kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md)
    docs/pingcastle/4.0/kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md not found

Auto-Fix Summary

5 issues fixed, 7 skipped across 3 files

Category	Fixes
Dale: misplaced-modifiers	2
Dale: passive-voice	1
Dale: undefined-acronyms	2

Skipped (needs manual review)	Reason

| docs/pingcastle/4.0/index.md:17 — Dale: passive-voice | 'The source code of the program is licensed to the Non-Profit OSL 3.0' — any active rewrite must name a licensor, which adds a factual claim not present in the source. Standard legal phrasing; left as written. |
| docs/pingcastle/4.0/index.md:542 — Dale: passive-voice | 'to determine if patches have been applied' in the scanner table — active alternatives ('the system received patches', 'patches are current') shift the technical meaning of what the startup scanner infers. |
| docs/pingcastle/4.0/index.md:729 — Dale: passive-voice | 'can also be misused by attackers' and 'No malicious payloads ... are present' sit inside the blockquoted Netwrix Security Statement. Editing a quoted official statement would misrepresent it. |
| docs/pingcastle/4.0/index.md:159 — Dale: passive-voice | 'If "Add User or Group" is grayed out' — adjectival state description of a UI control, not an agentive passive. Rewriting reads worse. |
| docs/pingcastle/4.0/enterpriseapiswagger.md:14 — Dale: passive-voice | 'If anonymous authentication is disabled' (also lines 53, 103) — stative/adjectival passive describing an IIS setting's state. No agent to promote; active rewrites are less clear. |
| docs/pingcastle/4.0/enterpriseapiswagger.md:14 — Dale: xy-slop | 'That popup comes from IIS requesting a Windows identity, not from the API's own login.' — positive-first, and the trailing negation carries real diagnostic information rather than being rhetorical filler. |
| docs/pingcastle/4.0/enterpriseapiswagger.md:113 — Dale: idioms | 'tick Preserve log' is a Britishism rather than an idiom; word-choice localization is a Vale concern, not a Dale rule. |

Ask @claude on this PR if you'd like an explanation of any fix.

[github-actions]

Code Review

No build-breaking, config, script, or workflow issues. This PR touches only markdown plus one sidebar entry — there are no changes to products.js, docusaurus.config.js, scripts/, or .github/workflows/.

Build/routing checks (all pass)

• sidebars/pingcastle/4.0.js — 'enterpriseapiswagger' resolves to the new docs/pingcastle/4.0/enterpriseapiswagger.md; syntax and placement are valid.
• Relative KB links (kb/scheduler-or-agent-deployment-returns-401-unauthorized-error.md) and images (kb/0-images/*.png) resolve correctly. pingcastle has no current version, so copy-kb-to-versions.mjs uses docs/pingcastle/{version}/kb as the destination and copies 0-images/ verbatim — the targets exist under docs/pingcastle/4.0/kb/ after prebuild/prestart. All five image filenames match docs/kb/pingcastle/0-images/ exactly.
• In-page anchors #enable-anonymous-authentication-in-iis and #troubleshoot-401-errors-and-credential-popups match their headings.

Findings

1. Possible bug in Connect-PCServer: the stored JWT may include literal quote characters (docs/pingcastle/4.0/enterpriseapiswagger.md)

$GLobal:PingCastle_JWT = $response.Content

Invoke-WebRequest's .Content is the raw response body. If /api/Agent/Login returns a JSON-encoded string, that body is "Bearer eyJhbGci..." — quotes included — and Invoke-PcApi then sends Authorization: "Bearer eyJ...", which most JWT middleware rejects with a 401.

The Swagger section of this same page implies the quotes are present: step 7 tells readers to copy the token "without the surrounding quotes". Worth confirming against a live server; if the quotes are there, the fix is:

$Global:PingCastle_JWT = $response.Content.Trim('"')

Flagging it because this is a copy-paste snippet — if it is wrong, every reader hits an unexplained 401 immediately after the page tells them 401s mean an expired token.

2. Minor — Invoke-PcApi throws on a caller-supplied Authorization header

"Headers" = @{"Authorization" = "$($Global:PingCastle_JWT)" } + $Headers;

PowerShell hashtable addition throws Item has already been added on a duplicate key, so -Headers @{Authorization = '...'} fails with a confusing error instead of overriding the default. Low impact given the intended usage; only worth changing if you want -Headers to be safely override-capable.

Note (no action required)

This is the first non-KB product doc in the repo to reference kb/... relative paths. It works, but it creates a cross-dependency: renaming or moving anything in docs/kb/pingcastle/0-images/ will now break the PingCastle 4.0 product build, not just the KB article. Low risk, since the KB article uses the same five images — but reviewers of future KB changes will not have an obvious signal.

Documentation content and style were out of scope for this review.

[RichardHNetwrix]

This code saves the login token with extra quote marks still attached, which will make the API reject it and show the same login error this is trying to help fix.