Skip to content

Commit bca0e91

Browse files
jtvioletjtviolet
authored
Merge pull request #163 from netwrix/change-tracker/add-creds-endpoint-docs
2 parents 5487f78 + c93cd90 commit bca0e91

File tree

3 files changed

+417
-6
lines changed

3 files changed

+417
-6
lines changed

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

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: "Credentials"
3+
description: "Credentials API for managing authentication credentials in ChangeTracker"
4+
sidebar_position: 10
5+
---
6+
7+
# Credentials
8+
9+
## Overview
10+
11+
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.
12+
13+
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.
14+
15+
## Endpoints
16+
17+
### Get Credentials
18+
19+
Retrieves credentials for a specified type and key.
20+
21+
**HTTP Request**
22+
```
23+
GET /credentials
24+
```
25+
26+
**Query Parameters**
27+
| Parameter | Type | Required | Description |
28+
|-----------|------|----------|-------------|
29+
| key | string | Yes | Unique identifier for the credentials |
30+
| type | string | Yes | Type of credentials (Shell, Database, FTP, Cloud, ESX, ITSM, Splunk) |
31+
32+
**Response**
33+
Returns a Credentials object with the following properties:
34+
35+
```json
36+
{
37+
"Version": 0,
38+
"CredentialType": "Shell",
39+
"DeviceOnlineDetection": "None",
40+
"Key": "example-key",
41+
"PublicKeys": ["string"],
42+
"Parameters": {"username": "user", "password": "***"},
43+
"Prompts": ["string"],
44+
"LastModifiedDateUtc": "2025-08-21T10:23:32.0000000Z",
45+
"IsTrusted": true,
46+
"NotTrustedReason": "",
47+
"DiscoveryTaskId": 0,
48+
"DiscoveryStatusMessage": "",
49+
"DiscoveryTaskStatus": "Complete"
50+
}
51+
```
52+
53+
### Create Credentials
54+
55+
Adds new credentials for a specified type and key.
56+
57+
**HTTP Request**
58+
```
59+
POST /credentials/add
60+
```
61+
62+
**Authentication**
63+
Requires authentication and the `CredentialsManage` permission.
64+
65+
**Request Body**
66+
```json
67+
{
68+
"Credentials": {
69+
"CredentialType": "Shell",
70+
"DeviceOnlineDetection": "None",
71+
"Key": "example-key",
72+
"PublicKeys": ["string"],
73+
"Parameters": {"username": "user", "password": "secret"},
74+
"Prompts": ["string"],
75+
"DecryptionErrors": {},
76+
"LastModifiedDateUtc": "2025-08-21T10:23:32.0000000Z",
77+
"IsTrusted": false,
78+
"NotTrustedReason": "",
79+
"DiscoveryTaskId": 0,
80+
"DiscoveryStatusMessage": "",
81+
"DiscoveryTaskStatus": "AwaitingPickup"
82+
}
83+
}
84+
```
85+
86+
**Parameters**
87+
| Parameter | Type | Required | Description |
88+
|-----------|------|----------|-------------|
89+
| CredentialType | enum | Yes | Type of credential (Unknown, Shell, Database, FTP, Cloud, ESX, ITSM, Splunk) |
90+
| DeviceOnlineDetection | enum | No | Method for detecting if device is online (None, Ping, TcpConnect) |
91+
| Key | string | Yes | Unique identifier for the credentials |
92+
| PublicKeys | array | No | List of public keys |
93+
| Parameters | object | Yes | Dictionary of credential parameters (e.g., username, password) |
94+
| Prompts | array | No | List of prompts |
95+
| IsTrusted | boolean | No | Whether the credential is trusted |
96+
97+
**Response**
98+
Returns the created Credentials object.
99+
100+
### Update Credentials
101+
102+
Updates existing credentials for a specified type and key.
103+
104+
**HTTP Request**
105+
```
106+
POST /credentials/update
107+
```
108+
109+
**Authentication**
110+
Requires authentication and the `CredentialsManage` permission.
111+
112+
**Request Body**
113+
Similar to the Create Credentials endpoint, but updates an existing credential.
114+
115+
**Response**
116+
Returns the updated Credentials object.
117+
118+
### Delete Credentials
119+
120+
Deletes credentials for a specified type and key.
121+
122+
**HTTP Request**
123+
```
124+
POST /credentials/delete
125+
```
126+
127+
**Authentication**
128+
Requires authentication and the `CredentialsManage` permission.
129+
130+
**Query Parameters**
131+
| Parameter | Type | Required | Description |
132+
|-----------|------|----------|-------------|
133+
| key | string | Yes | Unique identifier for the credentials to delete |
134+
| type | string | Yes | Type of credentials to delete |
135+
136+
**Response**
137+
Returns a success status code (200) if the credentials were successfully deleted.
138+
139+
## Credential Types
140+
141+
The following credential types are supported:
142+
143+
| Type | Description |
144+
|------|-------------|
145+
| Shell | Command-line shell credentials |
146+
| Database | Database connection credentials |
147+
| FTP | File Transfer Protocol credentials |
148+
| Cloud | Cloud service credentials |
149+
| ESX | VMware ESX/ESXi credentials |
150+
| ITSM | IT Service Management credentials |
151+
| Splunk | Splunk credentials |
152+
153+
## Online Detection Methods
154+
155+
The following online detection methods are available:
156+
157+
| Method | Description |
158+
|--------|-------------|
159+
| None | No online detection |
160+
| Ping | Use ICMP ping to detect if device is online |
161+
| TcpConnect | Use TCP connection to detect if device is online |

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

Lines changed: 59 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,67 @@
11
---
22
title: "API"
3-
description: "API"
3+
description: "ChangeTracker API Documentation"
44
sidebar_position: 20
55
---
66

77
# API
88

9-
Customers who run multiple instances of Netwrix Change Tracker in multiple regions can use the API
10-
to pull data from each instance and use that data build global reports containing data from all
11-
instances.
9+
Netwrix Change Tracker provides a comprehensive REST API that allows customers 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.
1210

13-
- [Agents](/docs/changetracker/8.1/integration/api/agents.md) – To pull data on agent statuses, configurations and group memberships, use
14-
the agentsRanked endpoint.
11+
## Authentication
12+
13+
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.
14+
15+
## Available APIs
16+
17+
The following API endpoints are available in Netwrix Change Tracker:
18+
19+
- [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.
20+
21+
- [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.
22+
23+
- [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.
24+
25+
## API Usage Best Practices
26+
27+
When working with the ChangeTracker API, consider the following best practices:
28+
29+
1. **Rate Limiting**: Implement appropriate rate limiting in your applications to avoid overwhelming the API.
30+
31+
2. **Error Handling**: Always implement proper error handling in your code to gracefully handle API errors.
32+
33+
3. **Authentication**: Store API credentials securely and never expose them in client-side code.
34+
35+
4. **Data Filtering**: When retrieving large datasets, use the available filtering parameters to limit the amount of data returned.
36+
37+
5. **Pagination**: For endpoints that return large collections, implement pagination to improve performance.
38+
39+
## Example Usage
40+
41+
Below is a simple example of how to use the API with PowerShell:
42+
43+
```powershell
44+
# Set up a session variable for the Admin user
45+
$myWebSession = GetAdminUserSession
46+
47+
# Define the API endpoint
48+
$uri = "https://changetracker.example.com/api/agentsRanked"
49+
50+
# Define the request body
51+
$requestBody = @{
52+
DeviceFilter = @{
53+
GroupNames = @()
54+
AgentDeviceIds = @()
55+
AgentDisplayNames = @()
56+
ExcludeProxiedDevices = $false
57+
OnlineStatuses = @("Online")
58+
}
59+
GetAgentGroupDetails = $true
60+
GetRelatedTemplates = $true
61+
} | ConvertTo-Json
62+
63+
# Make the API request
64+
$result = Invoke-RestMethod -Method Post -ContentType application/json -Uri $uri -WebSession $myWebSession -Body $requestBody
65+
```
66+
67+
For more detailed information about each API endpoint, please refer to the specific API documentation pages linked above.

0 commit comments

Comments
 (0)