|
|
|
|
@@ -1,15 +1,22 @@
|
|
|
|
|
---
|
|
|
|
|
name: reference_screenconnect_api
|
|
|
|
|
description: Working auth + method for the ACG ScreenConnect RESTful API extension (CTRLAuthHeader = raw secret, GetSessionsByName)
|
|
|
|
|
description: ACG ScreenConnect RESTful API auth + verified method surface (CTRLAuthHeader=raw secret); now wrapped by the /screenconnect skill
|
|
|
|
|
metadata:
|
|
|
|
|
type: reference
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
ACG ScreenConnect RESTful API extension — verified working call (2026-06-02, Howard). Credentials in vault `msp-tools/screenconnect.sops.yaml` (`credentials.username`, `credentials.api_secret`).
|
|
|
|
|
ACG ScreenConnect (CW Control) RESTful API Manager extension. Auth verified 2026-06-02;
|
|
|
|
|
full method surface + parameterized-installer deploy verified live 2026-06-21 (Howard).
|
|
|
|
|
**Now wrapped by the `/screenconnect` skill** (`.claude/skills/screenconnect/`) — use that
|
|
|
|
|
(`sc.py`/`sc_client.py`) rather than hand-rolling calls. Secret in vault
|
|
|
|
|
`msp-tools/screenconnect.sops.yaml` (`credentials.api_secret`).
|
|
|
|
|
|
|
|
|
|
- **Host:** `https://computerguru.screenconnect.com` **extension-guid:** `2d558935-686a-4bd0-9991-07539f5fe749`
|
|
|
|
|
- **Auth (the non-obvious part):** header `CTRLAuthHeader: <raw api_secret>` with **NO `Basic ` prefix and no base64** + header `Origin: https://computerguru.screenconnect.com`. Putting the secret in `Authorization: Basic <b64>`, or `CTRLAuthHeader: Basic <b64>`, both return 401. Raw secret in CTRLAuthHeader is what works.
|
|
|
|
|
- **Only method that exists:** `POST /App_Extensions/<guid>/Service.ashx/GetSessionsByName` with JSON body `{"sessionName":"<name>"}`. Every other `Get*` name (GetSessions, GetSessionList, GetHosts, ...) returns 500 `"Web method does not exist"`. Bad/missing params return 500 `"Unknown parameter: <x>"` — the valid param is `sessionName`.
|
|
|
|
|
- **Big limitation:** the match is on the session `Name` field, which is **blank for unattended access agents**, so this api user only enumerates a handful of named sessions — it CANNOT list a client's full machine inventory. For per-machine last-seen across a whole client, the API is not sufficient; read the ScreenConnect console (or a screen recording) instead. Session objects do carry `LastConnectedEventTime`, `LastEventTime`, `GuestInfo.LastActivityTime`, and custom props CP1=Company / CP2=Site / CP3=Tag.
|
|
|
|
|
- **Auth (the non-obvious part):** header `CTRLAuthHeader: <raw api_secret>` with **NO `Basic ` prefix and no base64** + header `Origin: https://computerguru.screenconnect.com`. `Authorization: Basic <b64>` or `CTRLAuthHeader: Basic <b64>` both 401. Raw secret in CTRLAuthHeader is what works. Endpoint: `POST /App_Extensions/<guid>/Service.ashx/<Method>`.
|
|
|
|
|
- **Verified methods (CORRECTS the old "only GetSessionsByName" note):** reads take a JSON object, writes take a POSITIONAL ARRAY.
|
|
|
|
|
- Reads: `GetSessionsByName {"sessionName":"<name>"}`, `GetSessionDetailsBySessionID {"sessionID":"<id>"}`, `GetSessionBySessionID`.
|
|
|
|
|
- Writes (gated in the skill): `SendCommandToSession ["<id>","<cmd>"]` (backstage command on the guest), `SendMessageToSession ["<id>","<msg>"]`, `UpdateSessionCustomProperties ["<id>",["cp1","cp2","cp3",...]]`. CP1=Company / CP2=Site / CP3=Tag (up to CP8).
|
|
|
|
|
- **Parameterized access installer (deploy):** the cloud serves a pre-keyed installer at `/Bin/ScreenConnect.ClientSetup.<ext>?e=Access&y=Guest&t=<name>&c=<CP1>&c=<CP2>&c=<CP3>...` (ext: msi/exe/pkg/deb/rpm/sh). The repeated `c=` self-tag the agent on install, so an RMM-pushed install self-places into the right Company/Site/Tag. Windows silent: `msiexec /i <file> /qn /norestart`. VERIFIED end-to-end on RMM-TEST-MACHINE 2026-06-21.
|
|
|
|
|
- **Real limitation (still true):** NO full-fleet inventory method — `GetSessions`/`GetAllSessions`/`GetSessionGroups` return 500 `"Web method does not exist"`. You CANNOT list a client's whole machine inventory via this API yet; needs Mike to update the RESTful API Manager extension (coord msg 60d9e876). Workaround: the installer sets session Name = machine name, so by-name lookup works post-install.
|
|
|
|
|
|
|
|
|
|
Used during the Dataforth Syncro asset cleanup as the third liveness source alongside Syncro + Bitdefender. See [[reference_acg_msp_stack]].
|
|
|
|
|
Used during the Dataforth Syncro asset cleanup as a liveness source. See [[reference_acg_msp_stack]] and the `/screenconnect` skill SKILL.md.
|
|
|
|
|
|
