# ScreenConnect (ConnectWise Control) API Reference - ACG instance

Live-verified spec for the ACG ScreenConnect cloud instance via the RESTful API
Manager extension. Source: ConnectWise ScreenConnect docs
(https://docs.connectwise.com/ScreenConnect_Documentation/Developers) + live
probing 2026-06-22.

## Connection & auth

- **Instance:** `https://computerguru.screenconnect.com`
- **Extension GUID:** `2d558935-686a-4bd0-9991-07539f5fe749` (RESTful API Manager)
- **Endpoint:** `POST <instance>/App_Extensions/<guid>/Service.ashx/<Method>`
- **Auth headers (VERIFIED):**
  - `CTRLAuthHeader: <raw api_secret>`  (NO "Basic" prefix - Basic auth 401s)
  - `Origin: https://computerguru.screenconnect.com`
  - `Content-Type: application/json`
- **Secret:** SOPS vault `msp-tools/screenconnect.sops.yaml` field `credentials.api_secret`.
- **Param convention:** reads take a JSON object; write methods take a POSITIONAL ARRAY.
- **Custom properties (this instance):** CP1=Company, CP2=Site, CP3=Tag (up to CP8).

## Methods (probed live 2026-06-22)

| Method | Params | Status | Notes |
|---|---|---|---|
| `GetSessionsByName` | `{"sessionName":"<name>"}` | VERIFIED | Matches the session Name field. "" returns blank-Name (unattended) sessions. CLI `sessions`. |
| `GetSessionDetailsBySessionID` | `{"sessionID":"<id>"}` | VERIFIED | Full session object (CustomPropertyValues, ActiveConnections, ...). CLI `session`. |
| `GetSessionBySessionID` | `{"sessionID":"<id>"}` | VERIFIED | Returns the session (or [] if none). |
| `SendCommandToSession` | `["<sessionID>","<command>"]` | VERIFIED (gated) | Runs a backstage command on the guest. CLI `send-command`. STATE-CHANGING. |
| `SendMessageToSession` | `["<sessionID>","<message>"]` | wired (array) | Chat message to the guest. CLI `send-message`. STATE-CHANGING. |
| `UpdateSessionCustomProperties` | `["<sessionID>",["cp1","cp2","cp3",...]]` | VERIFIED (gated) | Set CP1=Company/CP2=Site/CP3=Tag. CLI `set-properties`. STATE-CHANGING. |
| `CreateSession` | array (signature TBD) | EXISTS | Not the primary path - the installer creates access sessions. `raw` only. |
| `GetSessions` / `GetAllSessions` / `GetSessionGroups` | - | MISSING | "web method does not exist". Full-fleet inventory needs an extension update (Mike). |

## Parameterized access installer (the deploy capability)

The cloud serves a pre-keyed installer (no thumbprint param needed - the relay is
the instance subdomain). Build URL:

```
<instance>/Bin/ScreenConnect.ClientSetup.<ext>?e=Access&y=Guest&t=<name>&c=<CP1>&c=<CP2>&c=<CP3>&c=&c=&c=&c=&c=
```

- `<ext>`: msi | exe (Windows), pkg (macOS), deb | rpm | sh (Linux). VERIFIED: the
  `.msi` returns HTTP 200 / application/x-msi (~16 MB).
- `e=Access` (unattended access agent), `y=Guest` (the guest/installed role).
- `t=<name>`: the session Name (set it = machine name so by-name lookup works).
- repeated `c=`: custom properties in order (CP1=Company, CP2=Site, CP3=Tag, ... 8 slots).
- Windows silent install: `msiexec /i <file> /qn /norestart`.

CLI `build-installer --platform msi --name HOST --company X --site Y --tag Z`.

VERIFIED end-to-end 2026-06-22: RMM-pushed parameterized .msi -> session
`RMM-TEST-MACHINE` appeared with CustomPropertyValues `["AZ Computer Guru","Howard-VM","SC-TEST",...]`;
`send-command` created a marker file on the guest; `set-properties` re-tagged CP3.

## Error handling

- Missing method -> HTTP 500 body `"Web method does not exist"` (treated as expected,
  not a skill failure - not logged).
- Bad params on a real method -> HTTP 500 `"session manager fault"` /
  NullReferenceException (a bogus sessionID faults the same as a bad shape, so the
  generic fault does NOT distinguish - verify writes against a known test session).
- A bare `{}` to a write method faults: writes need the positional array.