Merge pull request #286 from netwrix/changetracker/api-overview-fix

Add authentication example script

Author: james-s-anderson

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

@@ -0,0 +1,63 @@
+---
+title: "Authentication"
+description: "Authentication"
+sidebar_position: 10
+---
+
+# 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 variable ```$NctSession``` is used to store the session information and can be used to make subsequent API calls.
+
+
+```powershell
+$url = Read-Host "Enter URL (https://192.168.1.1/api)"
+
+# Do not use this in production environments where trusted certificates are required
+$SkipCertificateCheck = Read-Host "Skip Certificate Check (y/n)"
+if ($SkipCertificateCheck -eq "y") {
+    $SkipCertificateCheck = $true
+}
+else {
+    $SkipCertificateCheck = $false
+}
+
+# Collect credentials
+$username = Read-Host "Enter Username"
+$password = Read-Host "Enter Password" -AsSecureString
+$ApiCredential = New-Object System.Management.Automation.PSCredential ($username, $password)
+Remove-Variable -Name password
+
+# Build request
+$body = @{
+    "UserName" = $ApiCredential.UserName
+    "Password" = $ApiCredential.GetNetworkCredential().Password
+    "RememberMe" = "false"
+} | ConvertTo-Json
+
+# Create new session
+$uri = "$($url)/auth/credentials"
+
+$NctSession = New-Object Microsoft.PowerShell.Commands.WebRequestSession
+
+try {
+    Invoke-RestMethod `
+    -Method Post `
+    -ContentType application/json `
+    -Uri $uri `
+    -Headers @{ Accept = 'application/json' } `
+    -Body $body `
+    -WebSession $NctSession `
+    -SkipCertificateCheck:$SkipCertificateCheck
+}
+catch {
+    Write-Error "Failed to create session: $_"
+    throw
+}
+finally {
+    Remove-Variable -Name body
+}
+```

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

@@ -10,15 +10,15 @@ Netwrix Change Tracker provides a comprehensive REST API that allows customers t
 
 ## Authentication
 
-All API endpoints require authentication. You'll need to include appropriate authentication credentials with your requests. The specific authentication method is detailed in each API documentation page.
+All API endpoints require authentication. See [Authentication](/docs/changetracker/8.1/integration/api/authentication.md) for an example script.
 
-## Available APIs
+## 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. This API allows you 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) – Register new agents with the system using the agents/register endpoint. This API allows you to register both direct agents installed on devices and proxied devices accessed through another agent.
+- [Register Agents](/docs/changetracker/8.1/integration/api/register-agents.md) – Normally used by agents to register with the Hub, but this API allows you to register proxied devices to be accessed through a proxy agent.
 
 - [Credentials](/docs/changetracker/8.1/integration/api/credentials.md) – 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.