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 le secret de votre tenant, contrôle l’expiration et vérifie que la méthode et le chemin correspondent à la requête réelle — puis expose la charge décodée à votre gestionnaire. L’enveloppe authentifiée « agir-comme-utilisateur » lie en plus l’opération, l’audience, les arguments de l’appel et un nonce à usage unique.

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.

L’enveloppe v2 est ce qui rend sûr un appel initié depuis le chat : sub est le principal d’audit sous lequel l’action s’exécute, aud lie le jeton à votre API pour qu’il ne puisse pas être rejoué contre un autre tenant, argsHash fige les arguments exacts pour que le corps ne puisse pas être altéré après signature, et le nonce à usage unique empêche le rejeu du jeton entier pendant sa durée de vie.

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.

sub

L’utilisateur final connecté pour lequel l’assistant agit, et le principal au regard duquel chaque action est autorisée et auditée. Obligatoire dans l’enveloppe v2.

aud

L’audience de l’API client à laquelle cette intention est liée — la séparation des tenants ne repose ainsi plus sur le seul secret HMAC. Rejetez tout jeton dont l’aud n’est pas la vôtre.

operation

L’opération, exprimée selon le transport, que cette intention autorise (par exemple méthode et chemin HTTP). La vérification échoue si elle ne correspond pas à la requête réelle.

argsHash

SHA-256 en hexadécimal minuscule des arguments canonicalisés de l’appel. Recalculez-le à partir du corps de la requête et rejetez en cas d’écart — cela ferme le rejeu par altération du corps.

nonce

Une valeur à usage unique que votre vérificateur enregistre et refuse d’accepter deux fois, fermant le rejeu pendant la durée de vie du jeton.

issuedAt, expiresAt

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

requiresStepUp (optional)

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 jetons v1 hérités — sans champ v, ne liant que la méthode et le chemin avec un userId facultatif — restent acceptés pendant la fenêtre de déploiement en double acceptation, afin que les backends déjà intégrés continuent de vérifier pendant votre mise à niveau. Les nouveaux jetons sont émis en v2.

Les échecs de vérification renvoient 403 avec un motif lisible par machine tel que missing-header, malformed, bad-signature, expired, method-mismatch ou path-mismatch ; la liaison renforcée « agir-comme-utilisateur » ajoute des contrôles d’opération, d’arguments, d’audience et de rejeu. Les mêmes chaînes de motif sont utilisées dans tous les SDK.

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

Lorsque 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 : la charge d’intention nomme l’utilisateur agissant (sub dans l’enveloppe authentifiée « agir-comme-utilisateur » ; userId dans une enveloppe anonyme héritée), et les actions d’écriture n’arrivent qu’après que Syncanix a exécuté son contrôle de confirmation.

L’autorisation reste la vôtre : traitez le sujet de l’utilisateur agissant (sub) comme l’identité à autoriser — exactement comme si cet utilisateur avait appelé le point de terminaison directement. Syncanix autorise que l’APPEL était intentionnel ; votre backend autorise ce que cet UTILISATEUR peut 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.