Widget proxy

This is the client path for the Mambo JavaScript widgets. Once the reference proxy is running on your origin, the only change on the front end is where the widgets send their requests. You keep the standard widgets and the standard initialisation; you only change apiRoot and key.

Repoint the widgets at the proxy

Point apiRoot at your own origin and set key to the placeholder your proxy expects. site is unchanged. userUuid is still required by the widgets, but the proxy ignores it and substitutes the authenticated user, so it no longer has any security significance.

Before — talking to Mambo directly:

JavaScript

Mambo.init({
apiRoot: 'https://api.mambo.io', // external host
key: 'YOUR_REAL_JS_KEY',         // the real key ends up in the page source
site: 'acmeinc',
userUuid: '0001',
lang: 'en'
});

After — talking to the proxy on your own origin:

JavaScript

Mambo.init({
apiRoot: 'https://app.acmeinc.com', // your own origin, same origin as the page
key: 'WIDGET',                      // placeholder — the proxy injects the real key
site: 'acmeinc',
userUuid: '0001',                   // ignored and overridden by the proxy
lang: 'en'
});

Note

The proxy must be served from the same origin as the page hosting the widgets. See the reference implementations for details.

Self-hosting the widget assets

The proxy keeps your widgets' API calls on your own origin and hides the JavaScript key. It does not change where the widget code, fonts, and images come from: those are still downloaded from Mambo's servers (https://versions.mambo.io).

If your goal is to eliminate all external requests from the browser, routing the API through the proxy is not enough on its own — you must also self-host the widget assets. Follow the on-premise recipe in Setup and configuration to serve them from your own domain.

Approved URLs

Mambo's JavaScript API validates the Referer of each request against the key's Approved URLs. Once requests come through the proxy, that check is no longer a meaningful security control — the proxy is a server-to-server client and sets the Referer itself. Your only task is to make it pass: add the single, exact URL the proxy sends (for example https://app.acmeinc.com) to the key's Approved URLs. Do not use a wildcard.

Content Security Policy

Because the widget assets are still loaded from https://versions.mambo.io (unless you self-host them, above), those Content Security Policy directives are unchanged. What changes is where the widgets make their API calls: with the proxy, connect-src should point at your own origin, not at Mambo.

HTTP

Content-Security-Policy: default-src 'self';
script-src 'self' https://versions.mambo.io;
img-src 'self' https://versions.mambo.io;
font-src 'self' https://versions.mambo.io;
connect-src 'self' https://app.acmeinc.com;

Compare this with the direct-integration CSP in Setup and configuration.

Login redirects

When Mambo returns an authentication-required response, the widgets redirect the browser to {apiRoot}/login. With the proxy, apiRoot is your own origin, so that route is served by your application. Handle it as part of your normal authentication flow, or configure the widgets' authentication.overrideLoginUrl option to point at your login page.