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 tu secreto de tenant, comprueba la caducidad y que el método y la ruta coinciden con la petición real, y expone el payload decodificado a tu 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 único de esta llamada de herramienta: úsalo como clave de idempotencia ante reintentos.
- tenantId
- Tu workspace (tenant) de Syncanix al que pertenece la llamada.
- userId
- El usuario final autenticado en cuyo nombre actúa el asistente. Ausente en llamadas sin contexto de usuario.
- method, path
- El método HTTP y la ruta que esta intención autoriza. La verificación falla si no coinciden con la petición real.
- issuedAt, expiresAt
- Marcas de tiempo Unix que acotan la vida de la intención. Las intenciones caducadas se rechazan.
- requiresStepUp
- Verdadero cuando la acción requiere una verificación reforzada reciente. Rechaza salvo que tu puerta de step-up se haya ejecutado.
Los fallos de verificación devuelven 403 con un motivo legible por máquina, uno de: missing-header, malformed, bad-signature, expired, method-mismatch, path-mismatch. Los motivos son idénticos en todos los SDK.
Actuar como usuario: lo que observa tu backend
Cuando el asistente actúa por un usuario autenticado, la guía de actuar como usuario cubre el flujo completo. A nivel de contrato, tu backend observa exactamente dos cosas: el userId del payload nombra al usuario actuante, y las acciones de escritura llegan solo después de que Syncanix haya ejecutado su puerta de confirmación.
La autorización sigue siendo tuya: trata userId como la identidad contra la que autorizar — exactamente como si ese usuario hubiera llamado al endpoint directamente. Syncanix autoriza que la LLAMADA fue 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.