Embeddable Chat Widget Security Automation: The Secret Key Never Reaches the Browser

A server-to-server API integration and a `<script>` tag embedded on a public website face fundamentally different threats. A server-side API key lives somewhere only the integrating team can read; a widget's public key lives in HTML that anyone with their browser's developer tools open can copy in seconds. Building a widget as if that difference did not exist — reusing the same kind of secret credential, trusting the browser's own Origin header without a server-side check, or letting one visitor's message volume draw down the same budget as every other customer's support traffic — turns a convenience feature into an open door.

A chat widget is often built as the last integration surface, after the server-to-server API already works, and it is tempting to simply reuse the same kind of credential and the same trust assumptions — because they already work for the case where the caller is a trusted backend, not an anonymous browser. Distinguishing failure reasons in an error response feels like better developer experience right up until an attacker is the one reading it. And a rate limit or an origin check that only exists at the CORS layer, rather than being re-verified as an actual authorization decision inside the handler, looks identical to a real check in every legitimate test — until someone sends a request that never goes through a real browser's CORS enforcement at all.

The widget's public `site_key` follows a fixed, validated format and resolves through `resolveWidgetSite()`, a function documented in its own source as never letting the public key double as a real credential. Resolution runs a multi-layer check: the site row must exist and be marked enabled; the site's own recorded `organization_id` must match the organization configured for this specific deployment — a defense-in-depth check that catches a site record somehow pointing at the wrong tenant, beyond what the database row alone would prevent; and the linked API key must exist, must not carry a revocation timestamp, and must not be past its expiration date if one is set. Any single failure among those returns a uniform `null`, which the caller turns into the same generic 403 response regardless of which specific condition actually failed — nothing in the response distinguishes a disabled site from a revoked key from a wrong-organization mismatch. Successful and failed resolutions are cached separately and briefly, with two different time-to-live values: 30 seconds for a successful resolution, so a busy widget conversation is not running two database SELECTs on every single message, and a shorter 10 seconds for a failure, so a site that gets re-enabled or a key that gets replaced starts working again quickly rather than waiting out the longer success TTL. A same-origin allowlist — normalized by stripping a trailing slash and lowercasing the host before comparison — is checked twice: once at the lightweight branding endpoint the widget calls on load, and again at the actual message-sending endpoint, since CORS reflecting the Origin header is a separate, earlier layer from the actual authorization decision made here. Before a message reaches the AI agent, a rate limit keyed to the specific site and the visitor's IP address runs through the same limiter infrastructure used for server-to-server API keys — layered on top of, never instead of, the tenant's own overall AI cost and quota ceiling, which still caps total spend regardless of how the rate limit behaves. Once past all of that, the widget's message runs through the exact same handler used by the authenticated, server-to-server `/v1/messages` path — the same memory, branding, quota and cost logic — so a widget conversation is not a second, thinner implementation carrying its own separate bugs. And if the underlying agent call itself throws an unexpected error, the endpoint still responds with HTTP 200 and a calm, generic apology message rather than an error payload, deliberately withholding information that could help someone probe the endpoint's internals.

A visitor to a client's public website opens their browser's developer tools out of curiosity and finds the widget's public `site_key` sitting in the page source, exactly as expected — it is meant to be public. They cannot do anything meaningful with it beyond loading the same widget: it is not the organization's real API key, and every request using it is still checked, server-side, against the linked key's own revocation and expiration status on every resolution.

A support lead later disables that widget site entirely, in response to an unrelated support request. A message sent through a still-open copy of the widget page ten seconds after the change is rejected: the failed resolution is cached for only 10 seconds, so within moments every request against that site key returns the same generic 403 regardless of whether the visitor is using an old page, a saved bookmark, or a deliberately copied snippet.

A public embed snippet stops being a liability just because it is, by necessity, visible to anyone who loads the page — the value that matters (the real API key) never crosses that boundary at all. A disabled site or a revoked key takes effect within seconds rather than staying live off a stale cache. One visitor sending an unusual volume of messages hits its own rate limit before it can meaningfully affect the tenant's shared AI budget. And an internal failure stays an internal failure — the visitor sees a calm apology, not a clue.

A team that needs the widget to behave completely differently from its own authenticated API integration — a separate model, a separate memory scope, a deliberately different behavior set — will not find that division here: the widget deliberately reuses the exact same handler logic as the server-to-server path, by design, precisely so the two never drift apart.

Reusing the same kind of secret key for a public embed as for a server integration means that key's exposure in a browser is a real credential leak. Centriu Synapse's widget instead uses a public identifier that is deliberately safe to expose, resolving to the real credential only inside the server, behind a multi-layer check that never tells a failed caller which specific condition it tripped.