Guard.ch in deine eigenen Tools integrieren

Wähle deinen Weg

• 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. Zu den API-Schritten
• Der Launcher-Link. Erstelle einen Link auf guard.ch/start mit der Zieladresse und lass ihn von einer Person öffnen. Die Untersuchung läuft in ihrem angemeldeten Guard.ch-Konto. Auch die Browser-Erweiterungen nutzen diesen Weg. Zum Launcher-Link

Alle Endpunkte und Felder findest du in der API-Referenz. Für KI-Assistenten gibt es eine eigene MCP-Anleitung.

Das brauchst du für die API

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

Die API nutzt HTTP und JSON, der Browser CDP. Du brauchst dafür kein zusätzliches SDK.

App-Schlüssel

Erstelle deinen App-Schlüssel unter Apps im Guard.ch-Dashboard. Du nutzt dafür dasselbe Konto wie bei Guard.ch.

• Bis zu zwanzig pro Konto. Ein Schlüssel pro Pipeline, Host oder Tool macht den Widerruf gezielt: Du kannst eine Integration stoppen, ohne die anderen zu unterbrechen.
• Ungenutzte Schlüssel laufen ab. Ein Schlüssel läuft ab, wenn er ein Jahr lang nicht genutzt wird. Beim Erstellen kannst du zusätzlich ein festes Ablaufdatum nach 30 Tagen, 90 Tagen oder einem Jahr setzen, passend zu deinem Rotationsrhythmus.
• Einmal sichtbar. Der Schlüssel wird genau einmal angezeigt, beim Erstellen. Wenn du ihn verlierst, widerrufe ihn und erstelle einen neuen.
• 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.

App-Schlüssel erstellen

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","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, erhältst du die erfolgreiche Antwort erneut, statt einen zweiten Browser zu öffnen. Das hilft bei Queues und wiederholten Jobs.

Die Antwort enthält die Sitzungs-ID, connectUrl für CDP, liveViewUrl für die Live-Ansicht, die Bildschirmgrösse und die noch freien Sitzungsplätze.

Den Browser steuern

Die JSON-Antwort des POST-Aufrufs ist in den folgenden Beispielen session. Verwende daraus connectUrl, um deinen CDP-Client zu verbinden:

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,
});

Danach automatisierst du den Browser wie gewohnt: 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.

Sitzungen und Nutzung verwalten

• 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 Sitzungen, die du nicht mehr brauchst. Jede laufende Sitzung belegt einen Platz; nach der letzten Verbindung bleibt er noch wenige Minuten belegt, bis die Sitzung automatisch endet.

Live-Ansicht und Übernahme

Zu jeder Sitzung gehört eine Live-Ansicht. Öffne sie, während dein Code läuft, und verfolge die Seite in Echtzeit. Bei einer Anmeldung, einem Captcha oder einer anderen Entscheidung kannst du Maus und Tastatur übernehmen und danach die Automation fortsetzen.

Falls das gewählte Browser-Image die Analyse unterstützt, kannst du sie in der Live-Ansicht einschalten. Sie zeigt Befunde während der Sitzung; nach deren Ende ist die Ansicht nicht mehr verfügbar.

Der Launcher-Link

Der Launcher liegt unter guard.ch/start. Öffnet eine Person den Link mit einer Zieladresse, meldet sie sich bei Bedarf an und gelangt zur Live-Ansicht der Untersuchung. Dein Tool braucht dafür weder Guard.ch-Zugangsdaten noch einen Token.

https://guard.ch/de/start?url=https%3A%2F%2Fexample.com

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

• url Die URL-kodierte Zieladresse. Für Links aus unseren Browser-Erweiterungen ist auch das Format ENCODED- mit anschliessenden Hex-Bytes möglich.
• 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.

Launcher-Link öffnen

Auf die Geräteflotte ausrollen

Für den interaktiven Start auf vielen Geräten kannst du die Browser-Erweiterungen zentral verteilen. Sie ergänzen den Launcher-Link um Rechtsklick-Menü, Symbolleisten-Popup und Tastenkürzel. Verwaltete Installationen lesen den workspace-Anmeldenamen aus der Browser-Richtlinie und führen Mitarbeitende über euer Single Sign-on.

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

• Bis zu drei gleichzeitige Sitzungen pro Person. Sind alle drei Plätze belegt, weist Guard.ch neue Sitzungen ab. Es gibt keine Warteschlange.
• 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 vor zu vielen neuen Sitzungen. Prüfe den Antwortstatus und verzögere weitere Versuche, wenn ein Limit erreicht ist.
• Der Launcher-Link trägt keine Berechtigung. Die Untersuchung läuft auf dem Konto der Person, die den Link öffnet. Auch wer einen weitergeleiteten Link erhält, muss sich mit dem eigenen Guard.ch-Konto anmelden.

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 Zielseite wird in unserer Infrastruktur geladen, 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.

Fragen zur Einbindung?

Wenn du Hilfe bei der Einbindung brauchst, melde dich bei uns.