Lass einen Agent die ganze Pipeline einrichten

Ein Agent tut hier nichts, bis du ihm einen Schlüssel gibst. Das Konto erstellen, die E-Mail des Inhabers verifizieren und den Schlüssel erzeugen sind Schritte im Browser, und genau darum geht es: Die Person, der die Abrechnung gehört, entscheidet, was der Agent erreichen kann, und der Agent hält genau eine Zugangsberechtigung, die du in einer Liste siehst und mit einem Klick widerrufst.

Es heißt auch, dass du nicht mit Tokens jonglieren musst. Der Agent berührt nie einen Konto-Endpunkt, hält nie eine Sitzung und kann seinen eigenen Zugriff nicht erweitern. Alles, was er tut, läuft über /v1/* mit dem Schlüssel, den du ihm gegeben hast.

Im Dashboard unter Organisation → API-Schlüssel fragt „Neuer Schlüssel“ nach einem Namen, einem optionalen Ablaufdatum und Projektzugriff. Lässt du das auf Alle Projekte, erreicht der Schlüssel alles in der Organisation. Wählst du eines, ist der Schlüssel daran gebunden. So hältst du einen unbeaufsichtigten Lauf in einem Wirkungsbereich, den du selbst gewählt hast. Der Wert erscheint nur einmal, kopiere ihn also direkt in die Umgebung des Agents.

Das Dashboard erstellt und widerruft Schlüssel, ändert aber nicht ihren Geltungsbereich. Willst du eine Bindung später erweitern oder einschränken, erzeugst du einen Ersatz und legst den alten still. Berechtigungen pro Aktion und Schlüssel sind geplant. Bis dahin hat ein Schlüssel die Berechtigungen der Mitgliederstufe: Er liest alles in seinem Bereich und darf frei erstellen, aktualisieren, umschalten, wiederholen und erneut abspielen. Löschen, Anzeigen und Rotieren von Signaturschlüsseln, Maskenrotation, Connector-Bereitstellung und Änderungen an der Abrechnung bleiben einem Admin oder Inhaber im Dashboard vorbehalten.

Drei Aufrufe: eine Quelle zum Empfangen, ein Ziel zum Senden und eine Verbindung dazwischen. Die Antwort der Quelle enthält die ingestUrl, und das ist das Einzige, was dein Anbieter braucht.

# Source. The ingestUrl is what your provider gets.curl -s "$API/v1/sources" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe", "provider": "stripe", "verifierConfig": { "secret": "whsec_..." } }'→ { "id": "src_...", "ingestUrl": "https://sdhk.events/<maskId>", ... } # Destination, then a connection joining the two.curl -s "$API/v1/destinations" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Billing", "type": "http", "url": "https://acme.example/hooks" }' curl -s "$API/v1/connections" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe → Billing", "sourceId": "src_...", "destinationId": "dest_..." }'

Wer einen bekannten Anbieter nennt, bekommt dessen Signaturverfahren gleich mit. Der Agent liefert also einen Schlüssel, statt ein Signaturformat zu recherchieren. Quellen nehmen auch eingehende E-Mails an, das behandelt der E-Mail-Leitfaden.

Ein Agent, der nur schreiben kann, rät. Dieselbe API liefert jedes Event mit seinem Prüfergebnis und jede Zustellung mit ihren Versuchen, und erst das macht es möglich, einen unbeaufsichtigten Lauf zu debuggen.

Ein Signaturfehler liefert dem Aufrufer bewusst ein vages 401. Würden wir einem nicht authentifizierten Absender erklären, welche Prüfung fehlgeschlagen ist, würde die Antwort zum Orakel. Der Grund wird stattdessen am Event gespeichert, wo ein authentifizierter Agent ihn lesen kann.

# Why did nothing arrive?curl -s "$API/v1/events?status=rejected" -H "authorization: Bearer $SDHK_KEY"→ rejectionReason: "signature_mismatch" | "timestamp_out_of_tolerance" | ... # Re-send one failed delivery. Free, creates nothing new.curl -s -X POST "$API/v1/deliveries/dlv_.../retry" -H "authorization: Bearer $SDHK_KEY" # Run an event through its connections again. Billable.curl -s -X POST "$API/v1/events/evt_.../replay" -H "authorization: Bearer $SDHK_KEY"

• /v1/spec.json ist das OpenAPI-3-Schema für jeden Endpunkt, und /v1 ist die interaktive Referenz auf Basis derselben Spezifikation.
• /llms.txt orientiert ein Modell schnell. /llms-full.txt ist die vollständige Anleitung, einschließlich der Fehlersemantik und der Limits, auf die man stößt.
• Fehler sind typisiert statt in Prosa. QUOTA_EXCEEDED und RATE_LIMITED sind eigene Codes, auf die du direkt verzweigen kannst. Plan-Limit-Fehler wie eine Connector-Obergrenze bleiben unter FORBIDDEN, und die Details stehen stattdessen in einer data-Payload (limit, current).

• Gib jedem Agent seinen eigenen Schlüssel. Einen zu widerrufen kostet dich dann nichts anderes, und die Spalte „Zuletzt genutzt“ zeigt dir, welcher Agent verstummt ist.
• Binde den Schlüssel an ein Projekt, es sei denn, der Agent verwaltet wirklich Projekte. Das ist heute die einzige verfügbare Einschränkung, und sie lässt sich nach dem Erzeugen des Schlüssels nicht ändern.
• Verzweige auf den Fehlercode, nie auf den Meldungstext. Meldungen sind für Menschen geschrieben, und das 401 beim Ingest ist absichtlich nichtssagend.
• Prüfe ?status=rejected, bevor du etwas erneut sendest. Eine Signatur, die nie verifiziert wurde, wird auch beim zweiten Versuch nicht verifiziert.
• Wenn ein Consumer ausgefallen ist, wiederhole lieber die Zustellung, statt das Event erneut abzuspielen. Die Wiederholung ist kostenlos, das erneute Abspielen wird abgerechnet.