Guard.ch in deine eigenen Tools integrieren

Jeder Weg nutzt dieselbe Plattform mit isolierten Browsern. Auch eine Sitzung, die dein Code erstellt, hat eine Live-Ansicht für eine Person. Unterstützt das gewählte Browser-Image die Analyse, kann sie diese bei Bedarf in der Ansicht einschalten.

Welchen Weg du willst, hängt davon ab, wer mit dem Ergebnis arbeitet. Liest es eine Person, gib ihr einen Launcher-Link. Liest es dein Code, nimm die API; die API-Referenz dokumentiert jeden Endpunkt und jedes Feld. Erledigt ein KI-Assistent die Arbeit, verbinde ihn stattdessen über MCP.

Drei Wege

• Die API. Erstelle eine Sitzung über REST, steuere sie mit Playwright, Puppeteer oder einem beliebigen CDP-Client und beende sie, wenn du fertig bist. Authentifiziert wird mit einem App-Schlüssel. Jede Sitzung hat eine eigene Live-Ansicht.
• Der Launcher-Link. Bau einen guard.ch/start-Link mit der Adresse darin und lass ihn eine Person öffnen. Die Untersuchung läuft in ihrem eigenen angemeldeten Guard.ch. Die Browser-Erweiterungen nutzen genau diesen Mechanismus.
• MCP. Ein KI-Assistent hängt sich an den gehosteten MCP-Endpunkt und steuert dieselben Browser mit seinen eigenen Tool-Aufrufen, ganz ohne dass du einen Client schreibst. Dieser Weg hat eine eigene Anleitung; hier geht es um die anderen beiden.

Bevor du startest

API-Basis

https://api.guard.ch/v8

Authentifizierung

Ein App-Schlüssel im Header Authorization: Bearer

Plan

Ein bezahlter Plan mit programmatischem Zugriff; die 30-tägige Testphase deckt ihn ab

Parallelität

Bis zu drei laufende Sitzungen pro Person; neue werden abgelehnt, nicht eingereiht

Launcher-Link

guard.ch/start, aufgerufen wie jede URL: kein Schlüssel, kein SDK

Sitzungsliste

Die Liste behält 30 Tage an Einträgen; die Seiten selbst werden nie gespeichert

Es gibt kein SDK, auf das du dich einlassen müsstest. Die API ist schlichtes HTTP mit JSON, die Browser-Seite ist normales CDP. Die Clients, die du ohnehin nutzt, funktionieren unverändert.

App-Schlüssel

Erstelle und verwalte Schlüssel mit deinem gemeinsamen Konto im Dashboard von browser.lol.

• Bis zu zwanzig pro Konto. Einer pro Pipeline, Host oder Tool hält den Widerruf chirurgisch präzise: Ziehst du einen Schlüssel, steht diese eine Integration still und sonst nichts.
• Das Ablaufdatum ist deine Wahl. Nie, 30 Tage, 90 Tage oder ein Jahr, festgelegt beim Erstellen. Alles, was unbeaufsichtigt läuft, fährt mit einem Datum sicherer.
• Einmal sichtbar. Der Schlüssel wird genau einmal angezeigt, beim Erstellen. Ein verlorener Schlüssel wird ersetzt, nicht wiederhergestellt: widerrufen und einen neuen erstellen.
• Gehört in den Header. Die API liest ihn aus Authorization: Bearer. Halte ihn aus Query-Strings heraus, wo ein Schlüssel in Browserverlauf, Proxy-Logs und Analysedaten landet.

Eine Sitzung erstellen

Ein POST startet einen isolierten Browser und gibt alles zurück, was du zum Steuern und zum Zuschauen brauchst:

curl -X POST https://api.guard.ch/v8/web/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"triage-4821","timeout":900,"country":"us","screen":{"width":1440,"height":900},"idempotencyKey":"ticket-4821"}'

• country Ausgangsstandort als Länder- oder Stadtcode (us, de, us-dal). Ohne Angabe nutzt die Sitzung den normalen Rechenzentrumsausgang des zugewiesenen Edge-Nodes.
• egress Auf residential gesetzt, verlässt die Sitzung das Netz über einen gehosteten Residential-Ausgang statt über einen Rechenzentrums-Ausgang, sofern der Plan das enthält. Lässt sich mit country kombinieren und wird gegen das Kontingent des Workspaces im laufenden Zyklus gezählt.
• proxy Deine eigene Proxy-URL, für einen Ausgang, den du selbst kontrollierst. Schliesst country und den Residential-Ausgang aus.
• screen Viewport als Breite und Höhe.
• url Eine http- oder https-Adresse, die sofort geöffnet wird.
• name Anzeigename für die Sitzungsliste im Dashboard. Lässt du ihn weg, wird einer erzeugt.
• idempotencyKey Wiederholungsschlüssel. Nutzt du ihn mit denselben Zugangsdaten erneut, wird die erfolgreiche Erstellung wiedergegeben, statt einen zweiten Browser zu öffnen: genau das, was du hinter einer Queue oder einem Job mit Retry willst.

Die Antwort trägt die Sitzungs-ID, connectUrl (den CDP-Websocket), liveViewUrl (die Ansicht für Menschen), die aufgelöste Bildschirmgrösse und die Parallelität, die dir noch bleibt.

Den Browser steuern

connectUrl ist ein gewöhnlicher CDP-Websocket mit eigenem Token pro Sitzung. Die üblichen Clients hängen sich direkt daran:

const browser = await chromium.connectOverCDP(session.connectUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example-shop.test/login");

const browser = await puppeteer.connect({
  browserWSEndpoint: session.connectUrl,
});

Ab da ist es deine gewohnte Automation: Navigation, Selektoren, Evaluation, Downloads und Tracing. Jemand aus deinem Team kann die Live-Ansicht öffnen, während dein Code den Browser steuert. Unterstützt das gewählte Image die Analyse, lässt sie sich dort einschalten.

Auflisten, beenden, Nutzung

• GET /web/sessions listet laufende Sitzungen; status=all nimmt die beendeten der letzten 30 Tage dazu, limit begrenzt die Seite
• GET /web/sessions/:id gibt eine Sitzung zurück, samt ihrer connectUrl, solange sie läuft
• DELETE /web/sessions/:id beendet eine Sitzung und gibt ihren Platz für den Workspace frei
• GET /web/usage gibt die aktuelle Parallelität, das Sitzungslimit des Plans und die Summen der letzten 30 Tage zurück

Beende, was du nicht mehr brauchst. Ein Platz hat einen Slot, und eine liegengelassene Sitzung hält ihn noch 4 Stunden nach der letzten Verbindung, bis sie von selbst endet.

Live-Ansicht und Übernahme

Jede Sitzung gibt zusätzlich eine Live-Ansicht zurück. Öffne sie, während dein Code läuft, und du siehst der Seite in Echtzeit zu. Nimm Maus und Tastatur, um an einer Anmeldung, einem Captcha oder einer Entscheidung vorbeizukommen, die du lieber selbst triffst, und lass die Automation danach weiterlaufen.

Eine Person kann an jedem Punkt eingreifen, ohne die Arbeit neu zu starten. Unterstützt das gewählte Image die Analyse, kann sie diese zusätzlich in der Ansicht einschalten. Die Analyse ist rein live: Nichts wird aufgezeichnet, und was sie gezeigt hat, ist mit dem Ende der Sitzung weg.

Der Launcher-Link

Der Launcher liegt unter guard.ch/start. Öffnest du ihn mit einem Ziel, übergibst du an den Browser der Person: Sie meldet sich bei Bedarf an, die Untersuchung startet und landet auf der Live-Ansicht. Dein Tool speichert weder ein Konto noch einen Token noch sonstige Guard.ch-Daten: Der Link ist die gesamte Integration.

Drei Query-Parameter, nur der erste davon ist Pflicht:

• url Die Zieladresse. Unsere Erweiterungen kodieren sie in einem kurzen Hex-Format: Auf das Präfix ENCODED- folgt die Adresse als Hex-Bytes in Grossbuchstaben, sodass die verdächtige URL nur als undurchsichtiges Token unterwegs ist, nicht als eingebetteter Link. Ein normal URL-kodierter Wert funktioniert genauso.
• location Der Ausgangsstandort, als Land (us) oder als Stadt (us-dal). Ohne Angabe wählt Guard.ch.
• workspace Der SSO-Anmeldename deines Workspaces. Damit wird eine noch nicht angemeldete Person durch euer eigenes Single Sign-on geleitet statt durch das allgemeine Formular. Es ist ein Routing-Hinweis und keine Zugangsdaten: Ein falscher Wert führt zurück zur normalen Anmeldung.

Ein Link ohne Sprachpräfix leitet auf den englischen Launcher um; die Query bleibt dabei erhalten. Für ein deutschsprachiges Team baust du guard.ch/de/start.

Auf die Geräteflotte ausrollen

Damit die ganze Belegschaft den interaktiven Weg hat, ohne dass du etwas baust, rollst du die Browser-Erweiterungen aus: Sie sind der Launcher-Link mit Rechtsklick-Menü, Symbolleisten-Popup und Tastenkürzel obendrauf, und die IT verteilt sie unternehmensweit. Verwaltete Installationen lesen den workspace-Anmeldenamen aus der Browser-Richtlinie, sodass jede Installation die Belegschaft von selbst über euer Single Sign-on anmeldet.

Denselben Anmeldenamen setzt du in die Launcher-Links, die deine eigenen Tools bauen. So melden sich Menschen bei deiner eigenen Integration genau gleich an wie bei den verwalteten Erweiterungen. Die Integrationsseite listet alles auf, was es fertig gibt.

Grenzen

• Parallelität ist die Einheit: bis zu drei pro Person. Bis zu drei gleichzeitig laufende Sitzungen für jede Person im Plan; sind alle drei belegt, wird abgelehnt statt eingereiht. Parallele Automatisierung skaliert über bis zu drei Browser nebeneinander, nicht über Bezahlung pro Aufruf.
• Aufrufe werden nicht gezählt. Weder Anfragen noch Sitzungen werden nach Volumen abgerechnet. Die Ausnahme ist der Residential-Ausgang: Er zählt gegen das Kontingent des Workspaces im Abrechnungszyklus.
• Für die Erstellung gilt ein Rate-Limit. Limits pro Minute, Stunde und Tag schützen die Plattform. Gewöhnliche Automation stösst nie daran, eine ausser Kontrolle geratene Schleife schon.
• Der Launcher-Link trägt keine Berechtigung. Er gibt für sich genommen nichts frei: Was läuft, läuft auf dem Konto der Person, die ihn öffnet, und ein weitergeleiteter Link landet schlicht vor deren Anmeldung.

Sicherheit

• App-Schlüssel gehören in den Authorization-Header. Halte sie aus URLs heraus, wo sie in Browserverlauf, Proxy-Logs und Analysedaten landen würden.
• Der CDP-Endpunkt jeder Sitzung trägt ein eigenes Token und stirbt mit der Sitzung.
• Ein Launcher-Link enthält keine Zugangsdaten und gibt nichts frei; die Anmeldung passiert auf guard.ch oder über euer eigenes SSO.
• Die verdächtige Seite lädt in unserer Infrastruktur, nie auf dem Rechner, der die API aufgerufen hat.
• Alles läuft über TLS, und Konto- und Sitzungs-Metadaten bleiben in der EU, unter demselben AVV wie der Rest des Produkts.

Nächste Schritte

Erstell unter Apps einen Schlüssel, leg eine Sitzung an, häng deinen CDP-Client daran. Für alles, was diese Schnittstelle nicht abdeckt, melde dich bei uns.