Laufzeit-API-Referenz

Drei Verträge verbinden Syncanix mit Ihrem laufenden Backend: der signierte Intent-Header, der jeden Tool-Aufruf autorisiert, die Act-as-User-Felder, die die Endnutzeridentität tragen, und die Witness-Daten, die API-Formen melden. Diese Seite ist die Referenz auf Feldebene; die Leitfäden behandeln die Abläufe.

Intent-Verifikation — der X-Syncanix-Intent-Header

Jeder Tool-Aufruf, den Syncanix an Ihr Backend sendet, trägt einen signierten Intent. Ihr SDK (oder Ihr eigener Code) prüft die HMAC-SHA256-Signatur mit Ihrem Tenant-Secret, das Ablaufdatum und die Übereinstimmung von Methode und Pfad mit der echten Anfrage — und reicht dann das dekodierte Payload an Ihren Handler.

X-Syncanix-Intent: base64url(JSON({ "payload": <obj>, "signature": "<hex>" }))
payload   = { toolCallId, tenantId, userId?, method, path, issuedAt, expiresAt, requiresStepUp? }
signature = hex(HMAC-SHA256(JSON(payload), secret))

toolCallId

Eindeutige ID dieses Tool-Aufrufs — als Idempotenzschlüssel bei erneuter Zustellung verwenden.

tenantId

Ihr Syncanix-Workspace (Tenant), zu dem der Aufruf gehört.

userId

Der angemeldete Endnutzer, für den der Assistent handelt. Fehlt bei Aufrufen ohne Nutzerkontext.

method, path

HTTP-Methode und Pfad, die dieser Intent autorisiert. Die Prüfung schlägt fehl, wenn sie nicht zur echten Anfrage passen.

issuedAt, expiresAt

Unix-Zeitstempel, die die Lebensdauer des Intents begrenzen. Abgelaufene Intents werden abgelehnt.

requiresStepUp

Wahr, wenn die Aktion eine frische Step-up-Verifikation verlangt. Ablehnen, solange Ihr Step-up-Gate nicht gelaufen ist.

Fehlgeschlagene Prüfungen liefern 403 mit einem maschinenlesbaren Grund — einem von: missing-header, malformed, bad-signature, expired, method-mismatch, path-mismatch. Die Gründe sind in jedem SDK identisch.

Act-as-User — was Ihr Backend beobachtet

Wenn der Assistent für einen angemeldeten Nutzer handelt, behandelt der Act-as-User-Leitfaden den Ablauf von Ende zu Ende. Auf Vertragsebene beobachtet Ihr Backend genau zwei Dinge: das userId-Feld benennt den handelnden Nutzer, und Schreibaktionen treffen erst ein, nachdem Syncanix sein Bestätigungs-Gate durchlaufen hat.

Die Autorisierung bleibt bei Ihnen: Behandeln Sie userId als die zu autorisierende Identität — genau so, als hätte dieser Nutzer den Endpunkt direkt aufgerufen. Syncanix autorisiert, dass der AUFRUF beabsichtigt war; Ihr Backend autorisiert, was dieser NUTZER darf.

Witness — der Laufzeit-Schema-Reporter

Die Witness-Middleware beobachtet Ihren API-Verkehr, um den Fähigkeitskatalog korrekt zu halten. Für jede beobachtete Anfrage und Antwort leitet sie einen Form-Deskriptor ab — die Struktur OHNE die Werte: Skalare melden nur ihren Typ (string, number, integer, boolean, null), Arrays die Form ihrer Elemente, Objekte die Formen ihrer Eigenschaften. Formen desselben Methode/Pfad-Paars werden über Beobachtungen hinweg zusammengeführt.

Werte durchlaufen VOR der Ableitung die Schwärzung, sodass der Ableiter nie sensible Zeichenketten sieht; divergente oder leere Strukturen fallen auf unknown zurück, statt zu raten.