Overview

A MonetizationOS proxy sits between your visitors and your origin server. It intercepts HTML responses, resolves visitor identity, calls the Surface Decision API, and applies personalization — all at the edge, with zero changes to your origin code.

For an introduction to what MonetizationOS proxies are and when to use them, see the Proxies concept page.

Provider implementations

Request pipeline

All proxy implementations share the same request pipeline. Each stage can short-circuit and return a response early when further processing is unnecessary.

Identity resolution

The proxy resolves the visitor's identity from cookies before calling the Surface Decision API:

• Authenticated users: identified by a JWT from the AUTHENTICATED_USER_JWT_COOKIE_NAME cookie.
• Anonymous users: identified by a session ID from the ANONYMOUS_SESSION_COOKIE_NAME cookie. If neither cookie is present, a new anonymous session ID is generated and set via Set-Cookie.

Surface Decision API call

The proxy calls POST /api/v1/surface-decisions with:

• SURFACE_SLUG — the configured surface to evaluate
• The resolved identity (JWT or anonymous identifier)
• The request path as the resource ID
• Any provider-specific request properties (e.g. geolocation, bot signals)

The response contains surfaceBehavior, componentBehaviors, resolved features, and identity. If the call fails, the proxy falls back to the unmodified origin response.

Surface behavior actions

Surface behavior covers HTTP-level response modifications:

• Set, add, or remove headers
• Set or add cookies
• Change status code and status text
• Replace the entire response body — e.g. for redirects, or blocked access

If a response body is set, the proxy returns immediately and skips component processing.

See Surface Workflows for examples of generating surface behavior content from workflows.

Component behavior actions

Component behaviors target CSS selectors in the HTML and support:

• Prepend / append — inject content inside a matched element
• Before / after — insert content adjacent to a matched element
• Remove — strip the matched element entirely
• Range replacement — replace content between two marker positions

Content types can be raw HTML, plain text, or typed web component elements.

See Component Workflows for examples of generating component behavior content from workflows, and WebContentSurfaceBehavior for details on supported content types and rendering behavior.

Error handling

If any stage after the origin request throws, the proxy catches the error and falls back to the original origin response, ensuring your site remains available if the MonetizationOS API is unreachable.