REST-API: Überblick

Verfügbarkeit

Die REST-API und Webhooks gibt es im Business-Plan. Niedrigere Pläne nutzen die Konsole. Die Seite API und Erweiterungen zeigt die fertigen Integrationen.

Prinzipien

Die API ist eine REST-API im engen Sinn:

• der gesamte Verkehr läuft über HTTPS auf Port 443;
• Antworten sind JSON;
• Antworten nutzen übliche HTTP-Statuscodes; eine fehlgeschlagene Authentifizierung liefert 401;
• die Authentifizierung läuft über Token, die in der Konsole ausgestellt und jederzeit widerrufen werden können;
• jeder Aufruf wird im hashverketteten Auditprotokoll des Arbeitsbereichs festgehalten.

Die folgenden Beispiele sind Richtwerte: Exakte Pfade und Parameter stehen in der Referenzdokumentation Ihres Arbeitsbereichs.

Authentifizierung

Ein API-Token stellen Sie in der Konsole im Bereich API aus. Behandeln Sie es als Geheimnis: Es handelt im Rahmen seines Geltungsbereichs im Namen des Arbeitsbereichs.

GET /v1/devices
Authorization: Bearer <IHR_TOKEN>
Accept: application/json

Legen Sie ein Token nie in versionierten Code. Nutzen Sie einen Secrets-Vault oder eine Umgebungsvariable.

Verfügbare Ressourcen

Die Ressourcenfamilien folgen der Produktstruktur:

• Sitzungen: assistierte Sitzung erstellen, den sechsstelligen Beitrittscode abrufen, Sitzungsstatus lesen;
• Geräte: installierte Agents, Online-Status, Gruppen auflisten;
• Audit: Ereignisse aus dem hashverketteten Protokoll lesen;
• Nutzer: Techniker und Rollen, im Business-Plan.

Jede Ressource ist paginiert; die Antworten enthalten die stabilen Kennungen für Folgeaufrufe.

Webhooks

Webhooks (Business-Plan) schieben Ereignisse in Ihre Infrastruktur, statt Sie zum ständigen Abfragen der API zu zwingen:

• Sitzung beendet;
• unbeaufsichtigtes Gerät verbunden oder getrennt;
• Auditereignisse, etwa eine bestätigte Dateiübertragung.

Ein zugestellter Webhook ist allein kein Beweis: Gleichen Sie sensible Ereignisse mit dem Auditprotokoll ab. Richten Sie Webhooks auf einen HTTPS-Endpunkt aus, den Sie kontrollieren; der Endpunkt muss über Port 443 erreichbar sein.

Typische Anwendungsfälle

• Bereitstellung automatisieren: Fragen Sie nach einem GPO- oder Intune-Rollout die Geräteliste ab, um zu bestätigen, dass der ganze Bestand online ist. Siehe Agent installieren und bereitstellen.
• Ein ITSM-Tool anbinden: Erstellen Sie eine assistierte Sitzung aus Ihrem Ticketsystem und holen Sie den Code ab, den Sie an die Person weitergeben.
• Überwachen: Empfangen Sie Sitzungsereignisse per Webhook und korrelieren Sie sie mit Ihrer eigenen Überwachung.

Konsole oder API?

Nutzen Sie die API, wenn die Arbeit repetitiv ist oder sich in ein anderes System integrieren muss: Provisionierung, Überwachung, Ticketabläufe. Nutzen Sie die Konsole für interaktiven Support. Beide steuern denselben Arbeitsbereich: Eine per API erstellte Sitzung erscheint in der Konsole und umgekehrt.

Beispiel: assistierte Sitzung erstellen

POST /v1/sessions
Authorization: Bearer <IHR_TOKEN>
Content-Type: application/json

{ "mode": "attended", "label": "Rechnungsarbeitsplatz" }

Die Antwort enthält die Sitzungskennung und den sechsstelligen Code, den Sie an die Person weitergeben. Die Anfrage und ihr Ergebnis stehen im Auditprotokoll, wie jede Aktion der Konsole.

Bewährte Praktiken

• Speichern Sie Token in einem Secrets-Vault, nie im Code.
• Lesen Sie Ereignisse aus dem Protokoll, statt die API ständig abzufragen.
• Testen Sie Webhooks vor dem Produktivbetrieb mit einem Test-Endpunkt.
• Widerrufen Sie das Token eines ausscheidenden Technikers sofort.

Weiterführendes

• Sicherheitsmodell und Verschlüsselung: was die API protokolliert und wie.
• Von ScreenConnect migrieren: die Neuverteilung der Agents bei einer Umstellung automatisieren.