Référence de l’API à l’exécution

Trois contrats relient Syncanix à votre backend en marche : l’en-tête d’intention signé qui autorise chaque appel d’outil, les champs agir-en-tant-qu’utilisateur qui portent l’identité de l’utilisateur final, et les données du witness qui rapportent les formes de votre API. Cette page est la référence au niveau des champs ; les guides couvrent les flux.

Vérification d’intention — l’en-tête X-Syncanix-Intent

Chaque appel d’outil que Syncanix envoie à votre backend porte une intention signée. Votre SDK (ou votre propre code) vérifie la signature HMAC-SHA256 avec votre secret de tenant, contrôle l’expiration et la correspondance méthode/chemin avec la requête réelle, puis expose le payload décodé à votre 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

ID unique de cet appel d’outil — utilisez-le comme clé d’idempotence en cas de relivraison.

tenantId

Votre espace de travail (tenant) Syncanix auquel l’appel appartient.

userId

L’utilisateur final connecté pour lequel l’assistant agit. Absent sur les appels sans contexte utilisateur.

method, path

La méthode HTTP et le chemin que cette intention autorise. La vérification échoue s’ils ne correspondent pas à la requête réelle.

issuedAt, expiresAt

Horodatages Unix bornant la durée de vie de l’intention. Les intentions expirées sont rejetées.

requiresStepUp

Vrai quand l’action exige une vérification renforcée récente. Rejetez tant que votre porte de step-up n’a pas tourné.

Les échecs de vérification renvoient 403 avec un motif lisible par machine, parmi : missing-header, malformed, bad-signature, expired, method-mismatch, path-mismatch. Les motifs sont identiques dans tous les SDK.

Agir en tant qu’utilisateur — ce que votre backend observe

Quand l’assistant agit pour un utilisateur connecté, le guide agir-en-tant-qu’utilisateur couvre le flux de bout en bout. Au niveau du contrat, votre backend observe exactement deux choses : le userId du payload nomme l’utilisateur agissant, et les actions d’écriture n’arrivent qu’après le passage de la porte de confirmation de Syncanix.

L’autorisation reste la vôtre : traitez userId comme l’identité à autoriser — exactement comme si cet utilisateur avait appelé l’endpoint directement. Syncanix autorise que l’APPEL était intentionnel ; votre backend autorise ce que cet UTILISATEUR a le droit de faire.

Witness — le rapporteur de schémas à l’exécution

Le middleware witness observe votre trafic d’API pour garder le catalogue de capacités exact. Pour chaque requête et réponse observées, il infère un descripteur de forme — la structure SANS les valeurs : les scalaires ne rapportent que leur type (string, number, integer, boolean, null), les tableaux la forme de leurs éléments, les objets les formes de leurs propriétés. Les formes d’un même couple méthode/chemin sont fusionnées entre observations.

Les valeurs passent par la rédaction AVANT l’inférence : l’inféreur ne voit jamais de chaînes sensibles ; les structures divergentes ou vides retombent sur unknown plutôt que de deviner.