API-Anfragen sicher testen

Teste Integrationen zuerst mit einem eigenen Testschlüssel und einem Actor-User mit begrenzten Rechten. Beginne immer mit einem lesenden Tool.

Kein API-Key im Hilfe-Center

Gib deinen echten API-Key niemals auf einer öffentlichen Webseite ein. Der Befehls-Generator unten verarbeitet nur URL, Tool-Name und JSON lokal im Browser. Er sendet nichts und verwendet im Ergebnis ausschließlich die Variable SYNCORE_API_KEY.

1. Schlüssel im Terminal setzen

PowerShell:

$env:SYNCORE_API_KEY = 'syn_DEIN_SCHLUESSEL'

Bash:

export SYNCORE_API_KEY='syn_DEIN_SCHLUESSEL'

2. Katalog testen

PowerShell:

$BaseUrl = 'https://syncore.example.com'
$Headers = @{ 'X-API-KEY' = $env:SYNCORE_API_KEY }
$Catalog = Invoke-RestMethod `
  -Method Get `
  -Uri "$BaseUrl/api/app-tools?includeStructure=1" `
  -Headers $Headers

$Catalog.tools | Select-Object name, module, sideEffect, confirmationRequired

Prüfe, ob nur die erwarteten Apps und Aktionen erscheinen. Ein zu großer Katalog deutet auf zu weit gefasste Rollen des Actor-Users hin.

3. Ausführbaren Befehl erzeugen

Übernimm einen Tool-Namen aus deinem aktuellen Katalog und baue die Eingabe nach dessen inputSchema.

API-Befehl erstellen Der Generator sendet keine Anfrage und speichert keine Zugangsdaten.

Lokal

Basis-URL Tool-Name

Eingabe als JSON-Objekt

PowerShell

curl

4. Ergebnis bewerten

HTTP 200 und ok: true: Transport, Schlüssel, Rechte und Tool-Ausführung waren erfolgreich.
Leere Daten sind nicht automatisch ein Fehler; möglicherweise gibt es im Datenscope keine passenden Datensätze.
needsSelection: true: Kandidaten anzeigen und eine Auswahl anfordern.
Bei einer Mutation den Zielzustand anschließend mit einem Lese-Tool prüfen.
HTTP 429: die Sekunden aus Retry-After abwarten und die Anfrage dann einmal wiederholen.
Fehler nach Statuscode behandeln und keine automatischen Endlosschleifen bauen. Die Meldungen und ihre Ursachen stehen unter Wenn eine API-Anfrage scheitert.

Mit OpenAPI-Tools testen

Lade die SynCore App-Tools OpenAPI-Datei herunter.
Importiere sie in Postman, Bruno oder Insomnia.
Setze die Server-Variable baseUrl auf deine SynCore-Instanz.
Hinterlege X-API-KEY als geschütztes Secret der lokalen Umgebung.
Rufe zuerst GET /api/app-tools?includeStructure=1 auf.
Kopiere einen sichtbaren Tool-Namen und dessen Eingabeschema in den POST-Request.

Die OpenAPI-Datei beschreibt den stabilen Transport. Welche fachlichen Tools verfügbar sind, bestimmt ausschließlich der aktuelle Katalog der Zielinstanz.

Abnahmereihenfolge

Für einen nachvollziehbaren Integrationstest empfehlen wir:

Ungültiger Key ergibt 401.
Gültiger Key liefert einen berechtigungsgefilterten Katalog.
Ein lesendes Tool liefert ok: true.
Ein absichtlich unzulässiges Eingabefeld beziehungsweise ein falscher Typ ergibt 400.
Ein schreibendes Tool wird erst nach Bestätigung ausgeführt.
Der geänderte Zustand wird per Readback nachgewiesen.
Ein gesperrter Schlüssel wird unmittelbar mit 401 abgewiesen.

Dokumentiere dabei Instanz, Version, Zeitpunkt, Schlüsselpräfix, Tool-Name und Ergebnis, aber niemals den vollständigen API-Key oder personenbezogene Antwortdaten.