RESTful API Manager
| RESTful API Manager | |
|---|---|
 |
|
| Author(s) | ConnectWise Labs |
| Latest version | 1.0.8 |
| Required server version | 22.3 |
Introduction
The RESTful API extension creates several HTTP endpoints that can retrieve and send ConnectWise ScreenConnect session information.
Installation
Install the extension from the Extension Marketplace. Once installed, you'll see the extension listed on your Extensions page.
Setup Authentication
1. Open the extension settings
From the Extensions page, click the Options menu for the RESTful API Manager. Select Edit Settings to open the Edit Extension Settings dialog.
2. Enter a random string for authentication
Enter a lengthy, random string into the Custom field for RESTfulAuthenticationSecret.
3. Add an HTTP Origin
Optionally, in the RESTfulAllowedOrigin field, add the HTTP Origin from where calls into the Extension will be made.
4. Save your settings
Click Save Settings to save your changes.
Usage
Authentication
- Requests from the extension must include an additional HTTP Header named CTRLAuthHeader with a value that matches the string set in RESTfulAuthenticationSecret
- If a value was specified in the RESTfulAllowedOrigin setting, it must also match the request’s Origin header
Making Requests
All requests must adhere to the following criteria:
-
HTTP Request Type:
-
GET if no data is changed – example GetSessionDetailsBySessionID, GetSessionsByName, GetSessionBySessionID
-
POST if data is added – example UpdateSessionCustomProperties, SendCommandToSession, SendMessageToSession
-
Important: If you are using Powershell and encounter an "Invoke-RestMethod : Cannot send a content-body with this verb-type" error, switch the request type from GET to POST.
-
-
Content-Type – application/json
-
Body data is passed as an array of parameters
Available Endpoints
| Value | Return |
|---|---|
| AddNoteToSession(string sessionID, string noteBody) | None |
| CreateSession(SessionType sessionType, string name, bool isPublic, string code, string[] customPropertyValues) | Created session |
| GetSessionBySessionID(string sessionID) | List of sessions |
| GetSessionDetailsBySessionID(Guid sessionID) | Session details |
| GetSessionsByFilter(string sessionFilter) | List of sessions |
| GetSessionsByName(string sessionName) | List of sessions |
| SendCommandToSession(string sessionID, string command) | None |
| SendMessageToSession(string sessionID, string byHost, string message) | None |
| SendToolboxItemToSession(string sessionID, string toolboxItemName) | None |
| UpdateSessionCustomProperties(string sessionID, string[] newCustomProperties) | None |
| UpdateSessionName(string sessionID, string newName) | None |
Note: AddNoteToSession is only available in extension versions greater than or equal to 1.0.6
Examples
The examples assume the following setting values:
- Destination hostname is https://control.screenconnect.com/
- RESTfulAuthenticationSecret is set to 97a0fe77-dc4a-4f37-a4da-cc12666
GetSessionDetailsBySessionID
PowerShell
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Type", "application/json")
$headers.Add("CTRLAuthHeader", "97a0fe77-dc4a-4f37-a4da-cc12666")
$headers.Add("Origin", "https://documentation.screenconnect.com")
$body = "[`"25950dd7-0230-4a72-9409-0b8c489684a2`"]"
$response = Invoke-RestMethod 'https://control.screenconnect.com/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/GetSessionDetailsBySessionID' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json
cURL
curl --location --request GET 'https://control.screenconnect.com/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/GetSessionDetailsBySessionID' --header 'Content-Type: application/json' --header 'CTRLAuthHeader: 97a0fe77-dc4a-4f37-a4da-cc12666' --header 'Origin: https://documentation.screenconnect.com' --data-raw '["25950dd7-0230-4a72-9409-0b8c489684a2"]'
SendCommandToSession
PowerShell
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Type", "application/json")
$headers.Add("CTRLAuthHeader", "97a0fe77-dc4a-4f37-a4da-cc12666")
$headers.Add("Origin", "https://documentation.screenconnect.com")
$body = "[`"25950dd7-0230-4a72-9409-0b8c489684a2`", `"ipconfig`"]"
$response = Invoke-RestMethod 'https://control.screenconnect.com/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/SendCommandToSession' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json
cURL
curl --location --request POST 'https://control.screenconnect.com/App_Extensions/2d558935-686a-4bd0-9991-07539f5fe749/Service.ashx/SendCommandToSession' --header 'Content-Type: application/json' --header 'CTRLAuthHeader: 97a0fe77-dc4a-4f37-a4da-cc12666' --header 'Origin: https://documentation.screenconnect.com' --data-raw '["25950dd7-0230-4a72-9409-0b8c489684a2", "ipconfig"]'