AI-Agent Structured Tool Access Automation: The Body Can Claim Anything; the Session Decides

A dedicated integration surface for a connected AI product to read and act on a specific person's data is a genuinely useful capability — and its single most consequential design decision, before any question of WHAT it can do, is WHO it is allowed to do it as. A request format that lets the caller specify which person's data to access, trusted at face value, effectively hands identity itself to whichever system is calling. The safer alternative — deriving identity strictly from the caller's own already-authenticated session — sounds obviously correct once stated, but still leaves a real design question: what should happen if a request ALSO includes a claimed identity that disagrees with the session? Ignoring it silently is a common, understandable choice. It is also the wrong one, because it destroys the one piece of evidence that something unusual was attempted.

Centriu Vértice built a dedicated, versioned integration surface specifically for a connected AI product to call structured, read-only operations against the product's own data, scoped to one specific member's own visible information. The surface exposes exactly two functions: a discovery endpoint (`GET /api/centriu/capabilities`) that names what is currently callable, and a single execution endpoint (`POST /api/centriu/tools/[name]`) that actually runs one of those named operations. The fix's own account is explicit about a deliberate naming decision behind this: the product already has an entirely separate internal chat feature, with its own guard logic and its own dedicated backend function, built for a different purpose — and giving this new, external-facing surface a name that differed from that existing feature only by language (an English word standing in for the Portuguese one already in use) would have created two features indistinguishable except by which language someone happened to be reading in, a structural trap for whoever maintains either one later. The new surface uses its own distinct name throughout.

The single most consequential decision inside this surface governs identity: which specific member's data a given call is allowed to touch. That identity is always derived from the caller's own already-authenticated session — obtained through the platform's standard session-resolution mechanism — and never from any value the incoming request body itself might supply. A request body MAY also include its own claimed identity value, and that field is not simply rejected outright the moment it appears: if present and it agrees with what the session already establishes, the call proceeds normally, treating the field as a harmless, redundant confirmation. If present and it DISAGREES with the session — the request body claims to be acting as somebody other than who the session says is actually calling — the request is refused outright with an explicit, specific error, and, just as importantly, that specific disagreement is written to an audit trail rather than simply discarded.

The fix's own account explains why silently ignoring a mismatched claim would have been the wrong design, even though the caller's actual permission would end up correctly restricted to the real session identity either way: silently ignoring the mismatch would still LEAVE NO RECORD that an attempt to claim a different identity had occurred at all — a request that innocuously supplies a matching identity and a request that suspiciously attempts to claim someone else's identity would look identical after the fact, because both would simply proceed as the real, session-derived identity with no distinguishing trace left behind. Refusing the mismatched request outright, and specifically logging that refusal, means a genuine attempt to make the system act as somebody else leaves a mark for whoever is watching for exactly that pattern — rather than disappearing into an ordinary-looking, successful call.

Every single operation reachable through this surface is read-only by construction, not merely by convention or policy: the underlying implementations expose only counting a result, reading one specific named record, or invoking one specific, pre-approved database function chosen from a fixed, named list — with no code path anywhere in the surface capable of performing a write of any kind, and no mechanism through which the calling AI system could submit its own arbitrary SQL or free-form query. A defect or a misconfiguration on this surface has, by construction, no mechanism available to alter any actual data, regardless of what a calling system might attempt to request.

A further, deliberate design choice governs how every response describes the absence of underlying data: a specific, explicit "no data" state is returned whenever there is genuinely nothing to report — for instance, a member whose real, live connection count in the network is actually zero — kept structurally distinct from a bare numeric zero a real, successful count could also legitimately produce. The fix's own reasoning is that collapsing the two into one identical-looking value would leave an AI system consuming this surface with no way to tell "there is confirmed, genuinely nothing here to report" apart from "something went wrong, or a capability didn't run" — a distinction that matters specifically because an AI system reasoning over this data has no other independent way to notice the difference on its own.

A call to this surface that supplies no claimed identity in its body, or one that matches the caller's own actual session, proceeds normally and returns data scoped to that real, session-derived member. A call that instead includes a claimed identity belonging to a DIFFERENT member than the one the session actually establishes is refused outright with an explicit error — and, distinct from simply failing silently, the specific attempt is written to an audit trail naming both the identity the session actually confirmed and the different identity the request had claimed, giving whoever reviews that trail a concrete, attributable record that an identity mismatch was attempted, rather than an ordinary-looking entry indistinguishable from any other successful call.

Centriu Vértice now offers a dedicated, read-only integration surface for a connected AI system, with identity strictly derived from the caller's authenticated session, a mismatched identity claim refused and specifically audited rather than silently discarded, every exposed operation read-only by construction, and every response honestly distinguishing a genuine zero from an absence of data.

This automation governs the identity-verification and read-only scope of Centriu Vértice's own dedicated AI-integration surface — it does not add any write capability for a connected AI system, does not replace or merge with the product's separate, pre-existing internal chat feature, and is specific to a product that needs a real, verifiable member identity behind every call; a purely anonymous or organization-wide AI integration with no per-person data to scope would not need this exact mechanism.

Deriving the acting identity strictly from a caller's authenticated session, while silently ignoring any identity a request body separately claims, would still correctly restrict every call to the real, verified identity — the actual permission outcome would be identical to refusing it outright. The difference is entirely in what happens to the EVIDENCE: silently ignoring a mismatch leaves a genuine attempt to claim someone else's identity looking exactly like an ordinary, successful call after the fact, while refusing it outright and writing the specific mismatch to an audit trail leaves a concrete, attributable record for whoever is watching for exactly that pattern — at the cost of one additional check and one additional log write per call.