fix(changetracker): improve API auth UX and move API to top-level sidebar

.github/workflows/openapi-dedup.yml

@@ -0,0 +1,89 @@
+name: OpenAPI Method Dedup
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    branches:
+      - dev
+    paths:
+      - 'static/openapi/**.yaml'
+      - 'static/openapi/**.yml'
+
+concurrency:
+  group: openapi-dedup-${{ github.event.pull_request.number }}
+
+jobs:
+  dedup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - name: Check if triggered by this workflow's own commit
+        id: bot-check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          COMMIT=$(gh api repos/${{ github.repository }}/commits/${{ github.event.pull_request.head.sha }} \
+            --jq '{author: .commit.author.name, message: .commit.message}')
+          MESSAGE=$(echo "$COMMIT" | jq -r '.message')
+          if echo "$MESSAGE" | grep -qE '^chore\(openapi\): deduplicate'; then
+            echo "Skipping: commit is from openapi-dedup workflow"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout PR branch
+        if: steps.bot-check.outputs.skip != 'true'
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.VALE_TOKEN }}
+
+      - name: Configure git identity
+        if: steps.bot-check.outputs.skip != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Set up Node.js
+        if: steps.bot-check.outputs.skip != 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        if: steps.bot-check.outputs.skip != 'true'
+        run: npm ci --ignore-scripts
+
+      - name: Run deduplication
+        id: dedup
+        if: steps.bot-check.outputs.skip != 'true'
+        run: |
+          OUTPUT=$(node scripts/deduplicate-openapi-methods.mjs)
+          echo "$OUTPUT"
+          if echo "$OUTPUT" | grep -q 'already clean'; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "summary=$OUTPUT" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit and push deduplicated spec
+        if: steps.bot-check.outputs.skip != 'true' && steps.dedup.outputs.changed == 'true'
+        env:
+          VALE_TOKEN: ${{ secrets.VALE_TOKEN }}
+        run: |
+          git add static/openapi/
+          git commit -m "chore(openapi): deduplicate HTTP methods in Change Tracker Hub spec
+
+          ${{ steps.dedup.outputs.summary }}
+
+          Generated with AI
+
+          Co-Authored-By: Claude Code <ai@netwrix.com>"
+
+          git remote set-url origin "https://x-access-token:${VALE_TOKEN}@github.com/${{ github.repository }}.git"
+          git push

.gitignore

@@ -22,9 +22,9 @@ docs/*/*/kb/**
 
 # Generated by npx docusaurus gen-api-docs (docusaurus-plugin-openapi-docs)
 # Ignore all generated files but keep _category_.json which is hand-authored
-docs/changetracker/8.1/integration/api/reference/*
-!docs/changetracker/8.1/integration/api/reference/_category_.json
-!docs/changetracker/8.1/integration/api/reference/index.md
+docs/changetracker/8.1/api/reference/*
+!docs/changetracker/8.1/api/reference/_category_.json
+!docs/changetracker/8.1/api/reference/index.md
 
 # KB copy script lockfile
 .kb-copy.lock

docs/changetracker/8.1/api/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md — Change Tracker 8.1 API Reference
+
+This file provides guidance for working in `docs/changetracker/8.1/api/`.
+
+## Directory layout
+
+```
+api/
+├── CLAUDE.md              # This file
+├── _category_.json        # Sidebar label and position for the API section
+├── overview.md            # Hand-authored API overview
+├── agents.md              # Hand-authored: agentsRanked endpoint guide
+├── authentication.md      # Hand-authored: auth flow and PowerShell example
+├── credentials.md         # Hand-authored: credentials CRUD endpoints
+├── register-agents.md     # Hand-authored: agent registration endpoint
+└── reference/             # Generated from OpenAPI spec — see below
+    ├── _category_.json    # Tracked; triggers structured sidebar injection
+    ├── index.md           # Tracked; hand-authored intro for the reference
+    ├── sidebar.ts         # Generated; loaded by products.js
+    └── *.mdx / *.json    # Generated; gitignored
+```
+
+## OpenAPI spec
+
+**Source:** `static/openapi/changetracker-hub-8.1.yaml`
+
+This spec is auto-generated by ASP.NET Swashbuckle. A key consequence: Swashbuckle exposes both GET and POST on virtually every endpoint (GET takes query-string params, POST takes a form body — same operation, different parameter-passing conventions). The generated reference would otherwise list every endpoint twice.
+
+### Deduplication
+
+`scripts/deduplicate-openapi-methods.mjs` removes the semantically incorrect method from each dual-method endpoint (keeps GET for reads, POST for mutations). It is:
+
+- **Idempotent** — if the spec is already clean, it exits without touching the file.
+- **Automatic in CI** — the `openapi-dedup` GitHub Actions workflow runs it whenever the YAML changes in a PR and commits the result back to the branch.
+- **Automatic on every build** — wired into `prestart`, `prebuild`, and `preci` in `package.json`, so it always runs before `gen-api-docs`.
+
+**17 endpoints intentionally keep both GET and POST** (auth flows, downloads, report rendering, and two `commandParser` endpoints where GET and POST do genuinely different things). These are listed in the `KEEP_BOTH` set at the top of the script.
+
+When the API team ships a new spec, no manual action is needed — push the YAML and the CI workflow handles the rest. For a full local refresh (dedup + clean stale pages + regenerate):
+
+```bash
+npm run openapi:sync
+```
+
+## Regenerating the reference locally
+
+The MDX files under `reference/` are gitignored (except `_category_.json` and `index.md`) and regenerated at build time. To regenerate manually:
+
+```bash
+# Full refresh — use when the OpenAPI spec has changed
+npm run openapi:sync
+
+# Quick regenerate only (no clean, no dedup — safe for minor changes)
+npx docusaurus gen-api-docs changetracker-hub
+```
+
+**`clean-api-docs` deletes `reference/_category_.json`** — `npm run openapi:sync` restores it automatically via `git checkout`. If you run `clean-api-docs` manually, restore it with:
+
+```bash
+git checkout -- docs/changetracker/8.1/api/reference/_category_.json
+```
+
+## Sidebar integration
+
+`reference/_category_.json` has `"customProps": { "isGeneratedApiSidebar": true }`. The `sidebarItemsGenerator` in `src/config/products.js` detects this flag and replaces the category's children with the structured sidebar from `reference/sidebar.ts` (loaded via `loadApiSidebarItems`).
+
+The `transformApiSidebarLabels` function in `products.js`:
+- Converts camelCase category labels to Title Case (e.g. `agentsRanked` → `Agents Ranked`)
+- Strips trailing periods from operation labels
+
+The `changetracker-hub` info page (an auto-generated landing page with a misaligned URL and label) is filtered out of the sidebar in `products.js`:
+
+```js
+.filter(item => !(item.type === 'doc' && item.id?.endsWith('/changetracker-hub')))
+```
+
+The `parseFrontMatter` hook in `docusaurus.config.js` also strips trailing periods from `title` and `sidebar_label` in generated MDX frontmatter (for the browser tab and breadcrumb). The root cause — trailing periods in OpenAPI `summary` fields — has been fixed directly in the YAML, so these hooks are now a safety net for future spec updates.
+
+## Auth scheme
+
+The security scheme is `type: http` / `scheme: bearer`. This renders the interactive explorer panel as **"AUTHORIZATION: HTTP"** with a **Bearer Token** input field, and auto-prepends `Bearer ` to the value. Do not change it back to `type: apiKey` — that shows a confusingly labeled plain-text input.
+
+## MDX gotchas
+
+- **Angle-bracket placeholders** like `<hub-url>` are parsed as JSX tags in MDX and cause build errors. Always wrap them in backticks: `` `https://<hub-url>/api` ``.
+- **Code fences** in hand-authored files must have a language specifier (`json`, `powershell`, `bash`, etc.) — bare ` ``` ` fences are flagged by linting.
+
+## Product name
+
+Always **Change Tracker** (two words). Never `ChangeTracker`.

docs/changetracker/8.1/integration/api/_category_.json → docs/changetracker/8.1/api/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "API",
-  "position": 20,
+  "position": 115,
   "collapsed": true,
   "collapsible": true,
   "link": {

docs/changetracker/8.1/integration/api/agents.md → docs/changetracker/8.1/api/agents.md

@@ -6,17 +6,17 @@ sidebar_position: 10
 
 # Agents
 
-To pull data on agent statues, configurations and group memberships, use the agentsRanked endpoint.
+To pull data on agent statuses, configurations, and group memberships, use the agentsRanked endpoint.
 
 ## /api/agentsRanked
 
 This call returns a list of agent details, including group and tracking template memberships.
 
 ### POST Request
 
-https://api/agentsRanked
+`https://<hub-url>/api/agentsRanked`
 
-```
+```json
 {
     "DeviceFilter": 
   {
@@ -40,12 +40,12 @@ DeviceFilter
 
 GetAgentGroupDetails
 
-- Specifies a value indicating whether to get agent group details.
+- Specifies whether to get agent group details.
 - Type – Boolean
 
 GetRelatedTemplates
 
-- Specifies a value indicating whether to get templates applied to the returned agents.
+- Specifies whether to get templates applied to the returned agents.
 - Type – Boolean
 
 #### DeviceFilter
@@ -65,7 +65,7 @@ AgentDeviceIds
 AgentDisplayNames
 
 - Filters by display names
-- Type –: Comma separated list of strings
+- Type – Comma separated list of strings
 - Example – ["NWX-4GMJGX3", "Azure 365 Cloud Reporting Group"]
 
 OnlineStatuses
@@ -76,10 +76,10 @@ OnlineStatuses
 
 ExcludeProxiedDevices
 
-- A value indicating whether to exclude proxied devices from the result set
+- Specifies whether to exclude proxied devices from the result set
 - Type – Boolean
 
-### Json Response Elements
+### JSON Response Elements
 
 - AgentGroups – A list of agent device group memberships
 - GroupsLookup – A lookup list of group id/key to display name
@@ -90,7 +90,7 @@ ExcludeProxiedDevices
 
 ### Example PowerShell
 
-The following PowerShell script will output the response to a CSV file with the following headers:
+The following PowerShell script outputs the response to a CSV file with the following headers:
 
 - DeviceName
 - FQDN
@@ -103,10 +103,9 @@ The following PowerShell script will output the response to a CSV file with the
 - IPv4
 - OnlineStatus
 
-To be able to trust self-signed certificates, each call to Invoke-RestMethod is made with the
--SkipCertificateCheck argument. This requires PowerShell 7.
+To trust self-signed certificates, each call to `Invoke-RestMethod` uses the `-SkipCertificateCheck` argument. This requires PowerShell 7.
 
-```
+```powershell
 # Declare script parameters and their default values. Override these defaults from the command line e.g. -HostUrl http://myliveserver/api
 param([string]$HostUrl = "https://localhost/api", [string]$AdminUser = "admin", [string]$AdminPwd = "password")
 # This script is intended to read and display agent details, including group and tracking templates

docs/changetracker/8.1/integration/api/authentication.md → docs/changetracker/8.1/api/authentication.md

@@ -1,16 +1,16 @@
 ---
 title: "Authentication"
 description: "Authentication"
-sidebar_position: 10
+sidebar_position: 20
 ---
 
 # Authentication
 
-The following PowerShell script is an example of how to authenticate to the ChangeTracker API.
-It prompts the user for the URL and credentials. It also asks wether to skip certificate validation or not and then creates a new session.
-Trusted certificates are recommended for all environments, but if you are using self-signed certificates in a lab environment, you have the option to skip certificate validation.
+The following PowerShell script shows how to authenticate to the Change Tracker API.
+It prompts for the URL, asks whether to skip certificate validation, then collects the user's credentials and creates a new session.
+Netwrix recommends trusted certificates for all environments, but if you are using self-signed certificates in a lab environment, you can skip certificate validation.
 
-The variable ```$NctSession``` is used to store the session information and can be used to make subsequent API calls.
+The `$NctSession` variable stores the session information for use in subsequent API calls.
 
 
 ```powershell

docs/changetracker/8.1/integration/api/credentials.md → docs/changetracker/8.1/api/credentials.md

@@ -1,16 +1,16 @@
 ---
 title: "Credentials"
-description: "Credentials API for managing authentication credentials in ChangeTracker"
-sidebar_position: 10
+description: "Credentials API for managing authentication credentials in Change Tracker"
+sidebar_position: 30
 ---
 
 # Credentials
 
 ## Overview
 
-The Credentials API allows you to manage authentication credentials used by ChangeTracker to connect to various systems and services. This API provides endpoints for creating, retrieving, updating, and deleting credentials for different credential types including Shell, Database, FTP, Cloud, ESX, ITSM, and Splunk.
+Use the Credentials API to manage authentication credentials that Change Tracker uses to connect to various systems and services. This API provides endpoints for creating, retrieving, updating, and deleting credentials for different credential types including Shell, Database, FTP, Cloud, ESX, ITSM, and Splunk.
 
-Credentials are identified by a unique key and include various parameters specific to the credential type. The API requires authentication and the `CredentialsManage` permission to perform operations.
+Each credential has a unique key and includes parameters specific to the credential type. The API requires authentication and the `CredentialsManage` permission to perform operations.
 
 ## Endpoints
 
@@ -134,11 +134,11 @@ Requires authentication and the `CredentialsManage` permission.
 | type | string | Yes | Type of credentials to delete |
 
 **Response**
-Returns a success status code (200) if the credentials were successfully deleted.
+Returns a success status code (200) when the deletion succeeds.
 
 ## Credential Types
 
-The following credential types are supported:
+Change Tracker supports the following credential types:
 
 | Type | Description |
 |------|-------------|

docs/changetracker/8.1/integration/api/overview.md → docs/changetracker/8.1/api/overview.md

@@ -6,27 +6,27 @@ sidebar_position: 20
 
 # API
 
-Netwrix Change Tracker provides a comprehensive REST API that customers can use to integrate with the platform programmatically. This is particularly useful for customers who run multiple instances of Netwrix Change Tracker in multiple regions, as they can use the API to pull data from each instance and build global reports containing data from all instances.
+Netwrix Change Tracker provides a comprehensive REST API that customers can use to integrate with the platform programmatically. This is particularly useful for customers who run multiple instances of Netwrix Change Tracker in multiple regions, as they can use the API to pull data from each instance and build global reports.
 
 ## Authentication
 
-All API endpoints require authentication. See [Authentication](/docs/changetracker/8.1/integration/api/authentication.md) for an example script.
+All API endpoints require authentication. See [Authentication](/docs/changetracker/8.1/api/authentication.md) for an example script.
 
 ## API Reference
 
-For an interactive reference of all Netwrix Change Tracker Hub API endpoints, see the [Netwrix Change Tracker Hub API Reference](/docs/changetracker/8_1/integration/api/reference/). The Netwrix Change Tracker Hub (the central management server) generates this reference directly from its OpenAPI 3.0 spec, covering all available endpoints with request/response schemas.
+For an interactive reference of all Netwrix Change Tracker Hub API endpoints, see the [Netwrix Change Tracker Hub API Reference](/docs/changetracker/8_1/api/reference/). This reference comes from the Change Tracker Hub (the central management server) OpenAPI 3.0 spec and covers all available endpoints with request/response schemas.
 
 The raw OpenAPI 3.0 spec (YAML) is also [available for download](/openapi/changetracker-hub-8.1.yaml).
 
 ## Available Endpoints
 
 The following API endpoints are available in Netwrix Change Tracker:
 
-- [Agents](/docs/changetracker/8.1/integration/api/agents.md) – Pull data on agent statuses, configurations, and group memberships using the agentsRanked endpoint. Use this API to retrieve detailed information about all agents in your environment, including their group memberships and applied tracking templates.
+- [Agents](/docs/changetracker/8.1/api/agents.md) – Pull data on agent statuses, configurations, and group memberships using the agentsRanked endpoint. Use this API to retrieve detailed information about all agents in your environment, including their group memberships and applied tracking templates.
 
-- [Register Agents](/docs/changetracker/8.1/integration/api/register-agents.md) – Agents normally use this API to register with the Hub, but you can also use it to register proxied devices accessed through a proxy agent.
+- [Register Agents](/docs/changetracker/8.1/api/register-agents.md) – Agents normally use this API to register with the Hub, but you can also use it to register proxied devices accessed through a proxy agent.
 
-- [Credentials](/docs/changetracker/8.1/integration/api/credentials.md) – Manage authentication credentials that Change Tracker uses to connect to various systems and services. This API provides endpoints for creating, retrieving, updating, and deleting credentials for different credential types including Shell, Database, FTP, Cloud, ESX, ITSM, and Splunk.
+- [Credentials](/docs/changetracker/8.1/api/credentials.md) – Manage authentication credentials that Change Tracker uses to connect to various systems and services. This API provides endpoints for creating, retrieving, updating, and deleting credentials for different credential types including Shell, Database, FTP, Cloud, ESX, ITSM, and Splunk.
 
 ## API Usage Best Practices