Referencia de la API en tiempo de ejecución

Los contratos del lado del cliente en runtime: la cabecera de intención firmada que verifica tu backend, el contrato actuar-como-usuario que observa, y la forma de los datos del witness.

Tres contratos conectan Syncanix con tu backend en ejecución: la cabecera de intención firmada que autoriza cada llamada de herramienta, los campos actuar-como-usuario que transportan la identidad del usuario final, y los datos del witness que informan de las formas de tu API. Esta página es la referencia a nivel de campo; las guías cubren los flujos.

Verificación de intención: la cabecera X-Syncanix-Intent

Cada llamada de herramienta que Syncanix envía a tu backend lleva una intención firmada. Tu SDK (o tu propio código) verifica la firma HMAC-SHA256 con el secreto de tu tenant, comprueba la caducidad y comprueba que el método y la ruta coinciden con la solicitud real, y luego expone el payload decodificado a tu manejador. El envelope autenticado de actuar-como-usuario enlaza además la operación, la audiencia, los argumentos de la llamada y un nonce de un solo uso.

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.

El envelope v2 es lo que hace que una llamada iniciada desde el chat sea segura de ejecutar: sub es el principal de auditoría con el que corre la acción, aud vincula el token a tu API para que no pueda repetirse contra otro tenant, argsHash fija los argumentos exactos para que el cuerpo no pueda manipularse después de la firma, y el nonce de un solo uso impide que el token completo se repita dentro de su vida útil.

toolCallId: ID único de esta llamada de herramienta: úsalo como clave de idempotencia ante reintentos.
tenantId: Tu workspace (tenant) de Syncanix al que pertenece la llamada.
sub: El usuario final con sesión iniciada por el que actúa el asistente, y el principal contra el que se autoriza y audita cada acción. Obligatorio en el envelope v2.
aud: La audiencia de la API del cliente a la que está vinculada esta intención, de modo que la separación de tenants ya no descansa solo en el secreto HMAC. Rechaza cualquier token cuyo aud no sea el tuyo.
operation: La operación, consciente del transporte, que esta intención autoriza (p. ej., método y ruta HTTP). La verificación falla si no coincide con la petición real.
argsHash: SHA-256 en hexadecimal en minúsculas de los argumentos canonicalizados de la llamada. Recalcúlalo a partir del cuerpo de la petición y rechaza en caso de discrepancia: esto cierra la repetición con manipulación del cuerpo.
nonce: Un valor de un solo uso que tu verificador registra y se niega a aceptar dos veces, cerrando la repetición dentro del TTL.
issuedAt, expiresAt: Marcas de tiempo Unix que acotan la vida de la intención. Las intenciones caducadas se rechazan.
requiresStepUp (optional): Verdadero cuando la acción requiere una verificación reforzada reciente. Rechaza salvo que tu puerta de step-up se haya ejecutado.

Los tokens v1 heredados —sin campo v, que solo enlazan método y ruta con un userId opcional— siguen aceptándose durante la ventana de despliegue de doble aceptación, de modo que los backends ya integrados siguen verificando mientras actualizas. Los tokens nuevos se emiten como v2.

Los fallos de verificación devuelven 403 con un motivo legible por máquina como missing-header, malformed, bad-signature, expired, method-mismatch o path-mismatch; el enlace reforzado de actuar-como-usuario añade comprobaciones de operación, argumentos, audiencia y repetición. Las mismas cadenas de motivo se usan en todos los SDK.

Actuar como usuario: lo que observa tu backend

Cuando el asistente actúa por un usuario con sesión iniciada, la guía de actuar como usuario cubre el flujo completo. A nivel de contrato, tu backend observa exactamente dos cosas: el payload de intención nombra al usuario que actúa (sub en el envelope autenticado de actuar-como-usuario; userId en uno anónimo heredado), y las acciones de escritura solo llegan después de que Syncanix haya ejecutado su control de confirmación.

La autorización sigue siendo tuya: trata el sujeto del usuario que actúa (sub) como la identidad contra la que autorizar, exactamente como si ese usuario hubiera llamado al endpoint directamente. Syncanix autoriza que la LLAMADA era intencionada; tu backend autoriza lo que ese USUARIO puede hacer.

Witness: el informador de esquemas en runtime

El middleware witness observa tu tráfico de API para mantener exacto el catálogo de capacidades. Para cada petición y respuesta observadas infiere un descriptor de forma — la estructura SIN los valores: los escalares informan solo de su tipo (string, number, integer, boolean, null), los arrays de la forma de sus elementos y los objetos de las formas de sus propiedades. Las formas del mismo método y ruta se fusionan entre observaciones.

Los valores pasan por redacción ANTES de la inferencia, así que el inferidor nunca ve cadenas sensibles; las estructuras divergentes o vacías colapsan a unknown en lugar de adivinar.