Reference implementations

The reference proxy is a small component you add to your backend. It serves both client paths — the widgets and the Node SDK — from a single mount point, and it has no web framework dependency, so it drops into an existing service.

You integrate it by implementing one function, which identifies the current user. Everything else — holding the keys, adding credentials, forwarding the request — is provided for you.

Get the proxy

Coming soon

Ready-to-run reference proxies are on their way. Download links and the dependency coordinates for the supported stacks will appear here once they are released. In the meantime the steps below show exactly what the integration looks like.

Identify the current user

The proxy needs to know which Mambo user a request belongs to. You provide that by implementing the resolver: given the incoming request, return the authenticated user's Mambo UUID, or an empty value if the request is not authenticated. The example below is Java; the other supported stacks expose the same single function.

Java

import io.mambo.proxy.AuthenticatedUserResolver;
import io.mambo.proxy.ProxyRequest;
import java.util.Optional;

public final class MyUserResolver implements AuthenticatedUserResolver {

  @Override
  public Optional<String> resolveMamboUuid( ProxyRequest request ) {
      // Look up your own session (cookie, token, header set by your auth layer)
      // and return that user's Mambo UUID.
      return MySession.of( request ).map( Session::mamboUuid );
  }
}

Note

This function is the authentication for the whole integration, and it is the only code you must write. Make sure it derives the user from a trusted server-side session — never from a value a client can set freely.

Configure the proxy

The proxy is configured with your Mambo settings through environment variables. All the credentials live here, on the server, and none of them reach a client.

Environment variable	Required	Description
MAMBO_BASE_URL	Yes	The Mambo API base URL, for example https://api.mambo.io
MAMBO_MOUNT_PATH	No	The path clients point at (default /mambo)
MAMBO_SITE	Yes	Your Site URL, for example acmeinc
MAMBO_JS_KEY	Yes (widget path)	Your JavaScript key, injected into widget requests
MAMBO_JS_REFERER	Yes (widget path)	The URL added as the Referer for widget requests; add it to the key's Approved URLs
MAMBO_PUBLIC_KEY	Yes (SDK path)	Your OAuth public key, used to obtain a token for SDK requests
MAMBO_PRIVATE_KEY	Yes (SDK path)	Your OAuth private key

The authenticated user is not a configuration value — it always comes from the resolver you implement.

Serve the proxy on the same origin

The proxy must answer on the same origin as the page that hosts the widgets — mount it behind the same domain (for example https://app.acmeinc.com/mambo routes to the proxy). If it runs on a different origin, the browser is once again making cross-origin calls, which defeats the purpose of the proxy.

Extending the proxy

The resolver is the only extension point most integrations need. If you need to change how requests are handled beyond that, each reference implementation is small and its source is available to build on.