Runtime API reference

Three contracts connect Syncanix to your running backend: the signed intent header that authorizes each tool call, the act-as-user fields that carry the end-user identity, and the witness payloads that report API shapes. This page is the field-level reference; the guides cover the flows.

Intent verification — the X-Syncanix-Intent header

Every tool call Syncanix sends to your backend carries a signed intent. Your SDK (or your own code) verifies the HMAC-SHA256 signature with your tenant secret, checks the expiry, and checks that the method and path match the actual request — then exposes the decoded payload to your 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

Unique ID of this tool call — use it as your idempotency key for retried deliveries.

tenantId

Your Syncanix workspace (tenant) the call belongs to.

userId (optional)

The signed-in end user the assistant is acting for. Absent on calls with no user context.

method, path

The HTTP method and path this intent authorizes. Verification fails if they do not match the actual request.

issuedAt, expiresAt

Unix timestamps bounding the intent lifetime. Expired intents are rejected.

requiresStepUp (optional)

True when the action requires a fresh step-up verification. Reject unless your step-up gate has run.

Verification failures return 403 with a machine-readable reason — one of: missing-header, malformed, bad-signature, expired, method-mismatch, path-mismatch. The reason strings are identical across every SDK.

Act-as-user — what your backend observes

When the assistant acts for a signed-in user, the act-as-user guide covers the end-to-end flow. At the contract level, your backend observes exactly two things: the intent payload userId names the acting user, and write actions arrive only after Syncanix has run its confirmation gate.

Authorization stays yours: treat userId as the identity to authorize against — exactly as if that user had called the endpoint directly. Syncanix authorizes that the CALL was intended; your backend authorizes what that USER may do.

Witness — the runtime schema reporter

The witness middleware observes your API traffic to keep the capability catalog accurate. For each observed request and response it infers a shape descriptor — the structure WITHOUT the values: scalars report only their type (string, number, integer, boolean, null), arrays report their item shape, objects report their property shapes. Shapes for the same method and path are merged across observations.

Values pass through redaction BEFORE inference, so the inferrer never sees sensitive strings; divergent or empty structures collapse to unknown rather than guessing.