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 eine signierte Intent. Ihr SDK (oder Ihr eigener Code) prüft die HMAC-SHA256-Signatur mit Ihrem Tenant-Secret, prüft den Ablauf und prüft, dass Methode und Pfad zur tatsächlichen Anfrage passen — und stellt dann die dekodierte Nutzlast Ihrem Handler bereit. Der authentifizierte Act-as-User-Envelope bindet zusätzlich die Operation, die Audience, die Aufrufargumente und einen Einmal-Nonce.

X-Syncanix-Intent: base64url(JSON({ "payload": <obj>, "signature": "<hex>" }))
payload   = { v: 2, toolCallId, tenantId, sub, aud, operation, argsHash, nonce, issuedAt, expiresAt, requiresStepUp? }
signature = hex(HMAC-SHA256(JSON(payload), secret))

// v1 (legacy) payloads — { toolCallId, tenantId, userId?, method, path, issuedAt,
// expiresAt } with no "v" field — remain accepted during the dual-accept window.

Der v2-Envelope ist es, der einen aus dem Chat ausgelösten Aufruf sicher ausführbar macht: sub ist die Audit-Identität, unter der die Aktion läuft, aud bindet das Token an Ihre API, sodass es nicht gegen einen anderen Tenant wiederverwendet werden kann, argsHash fixiert die exakten Argumente, sodass der Body nach dem Signieren nicht manipuliert werden kann, und der Einmal-Nonce verhindert, dass das gesamte Token innerhalb seiner Lebensdauer erneut eingespielt wird.

toolCallId

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

tenantId

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

sub

Der angemeldete Endnutzer, für den der Assistent handelt, und die Identität, gegen die jede Aktion autorisiert und auditiert wird. Im v2-Envelope verpflichtend.

aud

Die Kunden-API-Audience, an die dieser Intent gebunden ist — damit die Tenant-Trennung nicht mehr allein auf dem HMAC-Secret ruht. Lehnen Sie ein Token ab, dessen aud nicht Ihre eigene ist.

operation

Die transportbewusste Operation, die dieser Intent autorisiert (z. B. HTTP-Methode und Pfad). Die Verifikation schlägt fehl, wenn sie nicht zur tatsächlichen Anfrage passt.

argsHash

SHA-256 der kanonisierten Aufrufargumente als Kleinbuchstaben-Hex. Berechnen Sie ihn aus dem Request-Body neu und lehnen Sie bei Abweichung ab — das schließt Replay durch Body-Manipulation aus.

nonce

Ein Einmalwert, den Ihr Verifizierer aufzeichnet und kein zweites Mal akzeptiert — das schließt Replay innerhalb der TTL aus.

issuedAt, expiresAt

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

requiresStepUp (optional)

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

Ältere v1-Tokens — ohne v-Feld, nur an Methode und Pfad gebunden, mit optionaler userId — werden während des Dual-Accept-Rollout-Fensters weiterhin akzeptiert, sodass bereits integrierte Backends weiter verifizieren, während Sie aktualisieren. Neue Tokens werden als v2 ausgestellt.

Verifizierungsfehler geben 403 mit einem maschinenlesbaren Grund zurück, etwa missing-header, malformed, bad-signature, expired, method-mismatch oder path-mismatch; die stärkere Act-as-User-Bindung ergänzt Operations-, Argument-, Audience- und Replay-Prüfungen. In allen SDKs werden dieselben Grund-Strings verwendet.

Act-as-User — was Ihr Backend beobachtet

Wenn der Assistent für einen angemeldeten Nutzer handelt, deckt der Act-as-User-Leitfaden den End-to-End-Ablauf ab. Auf Vertragsebene beobachtet Ihr Backend genau zwei Dinge: Die Intent-Nutzlast benennt den handelnden Nutzer (sub im authentifizierten Act-as-User-Envelope; userId in einem älteren anonymen), und Schreibaktionen treffen erst ein, nachdem Syncanix sein Bestätigungs-Gate ausgeführt hat.

Die Autorisierung bleibt bei Ihnen: Behandeln Sie das Subjekt des handelnden Nutzers (sub) 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 tun 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.