Guard.ch in deine eigenen Tools einbinden
Verbinde deinen Code über REST und CDP mit einem Guard.ch-Cloud-Browser, oder gib eine URL per Launcher-Link an eine Person weiter.
Zwei Wege zur Einbindung
- Die API. Starte eine Session über REST mit den Apps, die sie braucht, steuere sie mit Playwright, Puppeteer oder einem anderen CDP-Client und beende sie, wenn du fertig bist. Du meldest dich mit einem API-Schlüssel an. Jede Session hat eine Live-Ansicht. Zu den API-Schritten
- Der Launcher-Link. Bau einen Link auf den Guard.ch-Launcher mit der Zieladresse und lass ihn von jemandem öffnen. Die Session läuft im eigenen, angemeldeten Guard.ch-Konto dieser Person. Auch die Browser-Add-ons nutzen diesen Weg. Zum Launcher-Link
Alle Routen und Felder stehen in der API-Referenz. Für KI-Assistenten gibt es die MCP-Anleitung.
Das brauchst du für die API
- API-Basis
- https://api.guard.ch/v7
- Authentifizierung
- Ein API-Schlüssel im Header Authorization: Bearer
- Plan
- Enterprise, mit API-Zugriff
Die API spricht HTTP und JSON, der Browser CDP. Ein zusätzliches SDK brauchst du nicht.
API-Schlüssel
API-Schlüssel erstellst und verwaltest du im Reiter «Agenten» deines Dashboards, unter «Erweitert».
- Bis zu zwanzig pro Konto. Ein eigener Schlüssel pro Pipeline, Host oder Tool macht das Widerrufen gezielt: Du stoppst eine Integration, ohne die anderen zu unterbrechen.
- Ungenutzte Schlüssel laufen ab. Ein Schlüssel gilt, bis du ihn widerrufst. Beim Erstellen kannst du zusätzlich ein festes Ablaufdatum nach 30 Tagen, 90 Tagen oder einem Jahr setzen, passend zu deinem Rotationsrhythmus.
- Nur einmal sichtbar. Der Schlüssel erscheint nur beim Erstellen. Verlierst du ihn, widerrufst du ihn und erstellst einen neuen.
- Gehört in den Header. Die API liest ihn aus Authorization: Bearer. Halte ihn aus Query-Strings heraus, sonst landet er in Browserverlauf, Proxy-Logs und Analysedaten.
Eine Session starten
Ein POST startet einen Cloud-Browser und liefert alles, was du zum Steuern und Zuschauen brauchst:
curl -X POST https://api.guard.ch/v7/web/sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "triage-4821",
"extensions": [
{ "id": "network.location", "settings": { "country": "US" } },
{ "id": "mail" }
],
"screen": { "width": 1440, "height": 900 },
"idempotencyKey": "ticket-4821"
}'extensionsDie Apps, mit denen die Session startet, als Liste aus id und optionalen Einstellungen, etwa Location Switch, Anonyme Mail oder die Sicherheits-Apps. Lässt du das Feld weg, startet die Session mit deinen immer aktiven Apps. Was dein Workspace erzwingt, ist in jedem Fall dabei.countryAusgangsstandort als Länder- oder Stadtcode (us, de, us-dal). Die ältere Art, die App Location Switch anzugeben; sie funktioniert weiterhin.egressMit residential geht die Session über einen Residential-Anschluss ins Netz, sofern dein Plan das enthält. Lässt sich mit country kombinieren und zählt zum Kontingent des Workspace im laufenden Zyklus. Steht für die App Home IP.proxyDie URL deines eigenen Proxys, für einen Ausgang, den du selbst kontrollierst. Steht für die App Proxy Connect und lässt sich weder mit country noch mit residential kombinieren.screenViewport als Breite und Höhe.urlEine http- oder https-Adresse, die sofort geöffnet wird.nameAnzeigename in der Session-Liste. Fehlt er, wird einer erzeugt.idempotencyKeyWiederholungsschlüssel. Schickst du ihn mit denselben Zugangsdaten nochmals, bekommst du die erfolgreiche Antwort zurück statt eines zweiten Browsers. Praktisch für Queues und wiederholte Jobs.
Die Antwort enthält die Session-ID, connectUrl für CDP, liveViewUrl für die Live-Ansicht, die Bildschirmgrösse und deine freien Session-Slots.
Den Browser steuern
In den Beispielen unten ist session die JSON-Antwort auf den POST. Verbinde deinen CDP-Client mit ihrer connectUrl:
Playwright
const browser = await chromium.connectOverCDP(session.connectUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example-shop.test/login");Puppeteer
const browser = await puppeteer.connect({
browserWSEndpoint: session.connectUrl,
});Ab da automatisierst du wie gewohnt: Navigation, Selektoren, Evaluation, Downloads und Tracing. Die Live-Ansicht kannst du öffnen, während dein Code den Browser steuert, und dort Apps ein- und ausschalten, auch die Sicherheits-Apps.
Sessions und Nutzung verwalten
GET /web/sessionslistet laufende Sessions; status=all nimmt die beendeten der letzten 30 Tage dazu, limit begrenzt die SeiteGET /web/sessions/:idgibt eine Session zurück, samt connectUrl, solange sie läuftPOST /vm/:vmId/extensionsschaltet Apps in einer laufenden Session ein; PATCH und DELETE auf /vm/:vmId/extensions/:id ändern oder beenden eine davonDELETE /web/sessions/:idbeendet eine Session und gibt ihren Slot freiGET /web/usagezeigt deine laufenden Sessions, das Limit des Plans und die Summen der letzten 30 Tage
Beende Sessions, die du nicht mehr brauchst. Jede laufende Session belegt einen Slot; nach der letzten Verbindung hält sie ihn noch wenige Minuten, bis sie von selbst endet.
Live-Ansicht und Übernahme
Jede Session hat eine Live-Ansicht. Öffne sie, während dein Code läuft, und verfolge die Seite in Echtzeit. Für eine Anmeldung, ein Captcha oder eine andere Entscheidung übernimmst du Maus und Tastatur und lässt die Automatisierung danach weiterlaufen.
Mit den Sicherheits-Apps zeigt die Live-Ansicht, was die Seite ist und tut, solange die Session läuft. Die Befunde gibt es nur live: Nach dem Ende der Session bleibt nichts davon.
Der Launcher-Link
Der Launcher liegt unter guard.ch/start. Wer einen Link mit Zieladresse öffnet, meldet sich bei Bedarf an und landet in der Live-Ansicht einer neuen Session. Dein Tool braucht dafür weder Guard.ch-Zugangsdaten noch einen Token.
https://guard.ch/de/start?url=https%3A%2F%2Fexample.comDer Link kennt drei Query-Parameter; nur url ist Pflicht:
urlDie URL-kodierte Zieladresse. Links aus unseren Browser-Add-ons können auch ENCODED- gefolgt von der Adresse als Hex-Bytes in Grossbuchstaben nutzen.locationDer Ausgangsstandort, als Land (us) oder Stadt (us-dal). Ohne Angabe startet die Session auf dem gewohnten Ausgang der Person.workspaceDer Anmeldename deines Workspace. Damit geht eine Person, die noch nicht angemeldet ist, über dein eigenes Single Sign-on statt über das allgemeine Formular. Er ist ein Routing-Hinweis, nie ein Zugang: Ein falscher Wert führt zur normalen Anmeldung.
Ein Link ohne Sprachpräfix leitet auf den englischen Launcher um und behält die Query; für ein deutschsprachiges Team baust du guard.ch/de/start.
Auf viele Geräte verteilen
Für Starts auf vielen Geräten verteilst du das Browser-Add-on zentral. Es öffnet den Launcher-Link per Rechtsklick-Menü, über ein Feld in der Symbolleiste oder per Tastenkürzel. Verwaltete Installationen lesen den workspace-Anmeldenamen aus der Browser-Richtlinie und schicken die Leute über dein Single Sign-on.
Denselben Namen setzt du in die Launcher-Links, die deine eigenen Tools bauen, damit die Anmeldung auf beiden Wegen gleich läuft. Die Integrationsseite zeigt alles, was es fertig gibt.
Limits
- 3 Sessions gleichzeitig pro Platz. Das ganze Team teilt sich die Sessions aller Plätze, und Workspace-Manager können einzelnen Mitgliedern ein Limit setzen. Sind alle Sessions belegt, lehnt Guard.ch neue ab, statt sie in eine Warteschlange zu stellen.
- Aufrufe werden nicht verrechnet. Weder Anfragen noch Sessions werden nach Menge abgerechnet. Ausnahme ist der Residential-Verkehr: Er zählt zum Kontingent des Workspace im Abrechnungszeitraum.
- Neue Sessions sind begrenzt. Limits pro Minute, Stunde und Tag schützen die Plattform vor zu vielen neuen Sessions. Erreichst du eines, prüf den Status der Antwort und warte, bevor du es nochmals versuchst.
- Der Launcher-Link gibt keinen Zugang. Wer ihn öffnet, meldet sich mit dem eigenen Guard.ch-Konto an. Leitest du den Link weiter, gibst du deinen Zugang nicht mit.
Sicherheit
- API-Schlüssel gehören in den Authorization-Header. Halte sie aus URLs heraus, sonst landen sie in Browserverlauf, Proxy-Logs und Analysedaten.
- Der CDP-Endpunkt jeder Session hat einen eigenen Token und endet mit der Session.
- Ein Launcher-Link enthält keine Zugangsdaten und gibt nichts frei; angemeldet wird bei Guard.ch oder über dein eigenes SSO.
- Die Zielseite lädt in unserer Infrastruktur, nie auf dem Gerät, das die API aufruft.
- Alles läuft über TLS, und Konto-, Workspace- und Abrechnungsdaten liegen in der EU.
Fragen zur Einbindung?
Brauchst du Hilfe bei einem der beiden Wege, melde dich bei uns.