Akamai EdgeWorkers Proxy

The MonetizationOS Akamai EdgeWorkers Proxy is an open source integration that adds server-side monetization decisions to static or edge-served HTML.

View on GitHub

What is Akamai EdgeWorkers?

Akamai EdgeWorkers runs serverless JavaScript on Akamai's global edge network, close to your users. The MonetizationOS proxy uses the responseProvider entry point to transform HTML responses before they reach the browser.

Why use the proxy worker?

The MonetizationOS Akamai proxy lets you evaluate and apply monetization behavior at the edge before HTML reaches the browser — with no changes to your origin code.

Installation and configuration

Prerequisites

Node.js 22+
An Akamai account with EdgeWorkers access
The Akamai CLI with EdgeWorkers and Sandbox modules installed
API credentials in ~/.edgerc with EdgeWorkers and Sandbox access

Install the CLI on macOS:

brew install akamai
akamai install edgeworkers
akamai install sandbox

Configure Property Manager variables

Set these in your Akamai property using the Set Variable behavior with the PMUSER_ prefix:

PMUSER variable	Description
`PMUSER_MOS_SECRET_KEY`	Your MonetizationOS secret key. Get it from environment settings.
`PMUSER_ORIGIN_URL`	The full URL of your origin server.
`PMUSER_SURFACE_SLUG`	The MonetizationOS surface to evaluate for every HTML request.
`PMUSER_AUTH_JWT_COOKIE`	Cookie name containing the authenticated user's JWT.
`PMUSER_ANON_COOKIE`	Cookie name for anonymous session identifiers.
`PMUSER_INJECT_SCRIPT_URL`	URL of the MonetizationOS web components script to inject when component transforms run (optional).
`PMUSER_MOS_HOST`	MonetizationOS API host. Defaults to `https://api.monetizationos.com`.
`PMUSER_MOS_ENDPOINTS_PREFIX`	Path prefix for custom endpoint routing. Defaults to `/mos-endpoints/`.
`PMUSER_MOS_API_PREFIX`	Internal Property Manager path prefix for worker `httpRequest()` sub-calls to `api.monetizationos.com`. Defaults to `/mos-webscale-api`. Do not use `/mos-api` — that path is reserved for client-facing authenticated routes such as `/mos-api/offer-redemptions`.
`PMUSER_SURFACE_DECISIONS_IGNORE_PATHS`	Comma-separated regex patterns for paths that should skip surface decisions (optional).
`PMUSER_ORIGIN_REQUEST_HEADERS`	JSON object of extra headers to send on every origin sub-request (optional).

For the full variable reference and Akamai-specific behavior, see the Akamai EdgeWorkers Proxy reference.

Property Manager setup

Complete these steps in Akamai Control Center Property Manager.

Origins

Configure origins so httpRequest() can reach:

Your website origin (hostname from PMUSER_ORIGIN_URL)
MonetizationOS API — api.monetizationos.com (used by the /mos-webscale-api rule below)

Default rule

EdgeWorkers

Enable: On
Identifier: your EdgeWorker ID (upload the bundle first)

Error handling

Continue on error: On (requests may reach the origin unprocessed if the worker fails)

Origin server

Origin type: Your Origin
Origin server hostname: your website origin
Forward Host Header: Origin Hostname
Cache Key Hostname: Incoming Host Header

MonetizationOS API proxy rule

Add a rule (for example MonetizationOS API Proxy) matching path /mos-webscale-api/*:

Modify Outgoing Request Path

Find: /mos-webscale-api/
Replace with: /
First occurrence only; keep query parameters

Origin server

Origin server hostname: api.monetizationos.com
Forward Host Header: Origin Hostname

This strips /mos-webscale-api/ and forwards to the MonetizationOS API origin for worker sub-requests without re-entering the EdgeWorker. This path is internal to the worker — it is separate from client-facing /mos-api/* authenticated routes handled by @monetizationos/proxy.

Build and deploy

1. Install dependencies

pnpm install

2. Build the bundle

pnpm run bundle

This produces monetizationos-akamai-proxy.tgz containing bundle.json and main.js.

3. Upload and activate

akamai edgeworkers upload --bundle monetizationos-akamai-proxy.tgz <edgeworker-id>
akamai edgeworkers activate <edgeworker-id> STAGING <version>
akamai edgeworkers activate <edgeworker-id> PRODUCTION <version>

Ensure the property EdgeWorkers behavior is enabled with responseProvider selected.

Local testing with Akamai Sandbox

The Akamai Sandbox runs the production EdgeWorkers runtime against your property configuration.

One-time setup:

pnpm run bundle
akamai edgeworkers upload --bundle ./monetizationos-akamai-proxy.tgz <edgeworker-id>
akamai sandbox create --hostname <your-hostname> --name mos-sandbox
akamai sandbox start

Test (sandbox listens on http://127.0.0.1:9550):

curl --header 'Host: <your-hostname>' http://127.0.0.1:9550/

Update code without restarting the sandbox:

pnpm run bundle && akamai sandbox update-edgeworker <edgeworker-id> ./monetizationos-akamai-proxy.tgz

Run tests

pnpm test           # watch mode
pnpm run test:run   # run once

For canonical setup details and updates, see the project README.

Next steps

Learn the broader concept and architecture in Proxies
Explore the request pipeline in the Proxy API reference

On this page