---
title: Use a proxy URL
description: 'Route Real User Monitoring data through a proxy you run: what the SDKs send, what the proxy must do, where to host it, and Node.js and Nginx examples.'
url: https://coralogix.com/docs/user-guides/rum/proxy-url/
product: rum
feature: RUM Overview
feature_id: rum-general
feature_identifier: rum/rum-general
last_updated: '2026-11-16'
---

# Use a proxy URL

Every Coralogix Real User Monitoring (RUM) SDK sends its data straight to the Coralogix ingress. However, some content blockers and corporate firewalls reject Coralogix domains and drop your data on its way to Coralogix. This means Coralogix can't monitor users whose browsers blocked the request.

To make sure your data reaches Coralogix, create and host a proxy server on your own domain to relay your outgoing data to Coralogix. The proxy keeps the public key out of your pages, lets you inspect the data before it leaves your network, and makes sure your data reaches Coralogix without being blocked. This article explains [how to build](#build-your-proxy) one with Node.js or Nginx, though you can use any server-side technology that can accept `POST` requests over HTTPS and forward them to Coralogix.

Coralogix does not host the proxy for you

Coralogix has chosen not to offer a custom-domain reverse proxy for Real User Monitoring the way some vendors do. Relaying telemetry through customer-branded domains expands the attack surface, complicates tenant isolation at ingestion, and obscures the data flow from end users and their compliance teams. Beacons sent straight to Coralogix under a per-tenant token keep the data processor relationship auditable and simpler to govern under GDPR, so first-party collection on your own infrastructure is the supported answer to ad blockers.

## What you need

* A server you control that can accept `POST` requests over HTTPS and reach `ingress.<region>.rum-ingress-coralogix.com`, where `<region>` is the region associated with your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md). For example, `eu1`.
* A Coralogix RUM application with its public key. The proxy holds the key instead of your pages.
* One of the [RUM SDKs](https://coralogix.com/docs/user-guides/rum/sdk-installation/overview.md) installed in your application.

Because the proxy runs entirely on your infrastructure, you don't need any Coralogix permissions.

## How it works

When you initialize the SDK, it checks whether the `proxyUrl` parameter holds a proxy server's address. When it does, the SDK sends every request to that address instead of to Coralogix. To let your proxy know which Coralogix [endpoint](#handling-rum-events-vs-recording-uploads) the request was bound for, the SDK appends a `cxforward` query parameter to that URL.

This example uses the Browser SDK:

```
CoralogixRum.init({

  // ...

  coralogixDomain: 'EU1',

  proxyUrl: 'https://www.example.com/rum',

});
```

The SDK builds the `cxforward` value on every request from your `coralogixDomain` and the endpoint for the kind of data it is sending. Set `coralogixDomain` to your Coralogix region in uppercase, such as `EU1`. The region appears in lowercase only inside the ingress hostname. When your account ingress has no region key, set the [`coralogixDomainUrl`](https://coralogix.com/docs/user-guides/rum/sdk-installation/javascript/browser-sdk/configuration/before-send-and-transport.md#ingress-url) parameter to the full ingress URL instead.

The value is URL-encoded so that it survives as a parameter value. For example, a proxy URL relaying RUM events to the EU1 ingress looks like this:

```
https://www.example.com/rum?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Fv1beta%2Flogs
```

The request goes to your proxy at `https://www.example.com/rum`, and `cxforward` tells it to relay the request body to `https://ingress.eu1.rum-ingress-coralogix.com/browser/v1beta/logs`. Everything the proxy needs in order to route a request is in that one parameter, so the proxy needs no per-endpoint configuration of its own.

`proxyUrl` must not include a query string

The SDK appends `?cxforward=` to `proxyUrl` as it appears. When `proxyUrl` already contains a query string, the request URL ends up with two `?` and the request fails.

Every RUM SDK accepts the proxy server's address in the same optional `proxyUrl` parameter:

* [Browser SDK](https://coralogix.com/docs/user-guides/rum/sdk-installation/javascript/browser-sdk/configuration/before-send-and-transport.md#proxy-url)
* [Android](https://coralogix.com/docs/user-guides/rum/sdk-installation/android/configuration/initialization.md#proxyurl)
* [iOS and tvOS](https://coralogix.com/docs/user-guides/rum/sdk-installation/apple/ios/configuration/options.md#coralogixexporteroptions-reference)
* [Flutter](https://coralogix.com/docs/user-guides/rum/sdk-installation/flutter/mobile/configuration/proxy-url.md#proxy-url)
* [React Native](https://coralogix.com/docs/user-guides/rum/sdk-installation/react-native/react-native-plugin/configuration/exporting-and-networking.md#proxy-url)
* [Roku](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/configuration/options.md#options)

### Authorization

When the public key is set in the SDK, both kinds of request carry an `Authorization: Bearer <public key>` header. Your proxy can forward that header unchanged, or leave the key out of the SDK altogether and add the header itself. See [Build your proxy](#build-your-proxy).

### Traffic the proxy does not carry

The proxy carries only the data the SDK sends, never the files it loads. A Browser SDK installed from the CDN downloads its script from `cdn.rum-ingress-coralogix.com`, and Session Recording loads its compression library from the same host, falling back to `cdnjs.cloudflare.com`. When both hosts are blocked, Session Recording stops, and a proxy does not change that.

The SDK also keeps its own calls to the proxy out of the network events it reports, so they never appear in your RUM data.

### Handling RUM events vs recording uploads

Each request's `cxforward` parameter names one Coralogix ingress endpoint, chosen by the kind of data the request carries:

| Data type                                                                           | Endpoint                          | Body                                                               |
| ----------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------ |
| RUM events: logs, errors, network requests, Web Vitals, and user interactions       | `/browser/v1beta/logs`            | JSON, with `Content-Type: application/json`                        |
| [Recording uploads](#recording-uploads): Session Recording segments and screenshots | `/browser/alpha/sessionrecording` | `multipart/form-data`, with a `chunk` field and a `metaData` field |

### Recording uploads

The ingress endpoint for recording uploads is included in `cxforward`, but requests of this type have a different kind of body. Session Recording does not send a session's recording as a single file at the end of the session. Rather, the SDK uploads that recording continuously in segments of up to 1 MB, one request per segment.

A `multipart/form-data` body is divided into named fields, each with its own headers and its own encoding. A recording upload uses both:

* `chunk`: Recording data itself, gzip-compressed by the SDK.
* `metaData`: JSON object describing the segment, sent uncompressed.

For example, a recording upload might look like this:

```
POST /rum?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Falpha%2Fsessionrecording HTTP/1.1

Host: www.example.com

Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryAbc123

Content-Encoding: gzip



------WebKitFormBoundaryAbc123

Content-Disposition: form-data; name="chunk"

Content-Type: application/octet-stream



<gzip-compressed recording bytes>

------WebKitFormBoundaryAbc123

Content-Disposition: form-data; name="metaData"



{"segmentIndex":0,"segmentSize":48213,"segmentTimestamp":1762425600000,"sessionCreationDate":1762425000000,"sessionId":"0f9c4a1e","snapshotId":"","application":"my-app","subIndex":-1}

------WebKitFormBoundaryAbc123--
```

In this example, the `Content-Type` header specifies the boundary string that tells the receiver where one field ends and the next begins. The request-level `Content-Encoding: gzip` describes the `chunk` field alone: the body as a whole is a multipart envelope, not a gzip stream, so a proxy that reads that header and decompresses the body corrupts the recording. Both are why the proxy has to [forward the body unchanged](#build-your-proxy).

### Requests without the `cxforward` parameter

With some SDKs, `cxforward` can be omitted altogether. The [Browser SDK](https://coralogix.com/docs/user-guides/rum/sdk-installation/javascript/browser-sdk.md) and the [Roku SDK](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku.md) let you remove it by setting [`ignoreProxyUrlParams`](https://coralogix.com/docs/user-guides/rum/sdk-installation/javascript/browser-sdk/configuration/before-send-and-transport.md#ignoreproxyurlparams) to `true`.

Since the proxy server uses [the endpoint included in the `cxforward` parameter](#handling-rum-events-vs-recording-uploads) to relay data based on its content type, requests without the parameter arrive at the proxy with nothing for it to route on. Your proxy must therefore tell them apart by examining the content type: `multipart/form-data` indicates a recording upload; `application/json` indicates RUM events.

## Build your proxy

Your proxy must do all the following with every request it receives:

1. Forward to a fixed ingress: Send requests to `https://ingress.<region>.rum-ingress-coralogix.com`, or to the URL you set in `coralogixDomainUrl`. Take only the path from the `cxforward` query parameter, and only when that path is `/browser/v1beta/logs` or `/browser/alpha/sessionrecording`. Reject anything else.
2. Forward the body unchanged: Pass the bytes through as received, with the `Content-Type` header, which carries the multipart boundary, and `Content-Encoding`. Do not decompress a [recording upload](#recording-uploads).
3. Authenticate: Forward the `Authorization` header, or set `Authorization: Bearer <public key>` on the proxy and leave the public key out of the SDK's initialization.
4. Forward the user's IP address: Coralogix reads the user's address from the first public address in `X-Forwarded-For` and derives their location from it, so append the client address to that header. Without it, every user appears to be located wherever the proxy runs. This does not apply when [`collectIPData`](https://coralogix.com/docs/user-guides/rum/sdk-installation/javascript/browser-sdk/configuration/before-send-and-transport.md#collect-ip-data) is `false`. The address also has to be in a form Coralogix reads as public, so see [Troubleshooting](#troubleshooting) when every user resolves to the same place.
5. Return the same status code Coralogix returns: The SDK does not retry a failed request, and a failed recording upload stops Session Recording for the rest of the session.
6. Accept bodies of at least 4 MB: A recording segment reaches 1 MB, and the multipart envelope around it adds more, so a request can exceed 1 MB.
7. Serve on HTTPS: A page served over HTTPS cannot send requests to an `http://` proxy.
8. Drop cookies: When the proxy shares your application's origin, the browser sends your site's cookies with every request. Do not pass them on to Coralogix.

A proxy that trusts `cxforward` is an open relay

The client controls `cxforward`, so a proxy that forwards to whatever URL the parameter names lets anyone use your server to send requests to any host. Fix the ingress host on the server and take only the path from `cxforward`.

## Host your proxy

When possible, serve the proxy from the same origin as your application, for example as a `/rum` path on the reverse proxy or load balancer that already serves your site. The requests then go to your own domain, and the browser sends no Cross-Origin Resource Sharing (CORS) preflight.

When the proxy has an origin of its own, such as `https://rum.example.com`, it must answer that preflight. Respond to `OPTIONS` with these headers, and send `Access-Control-Allow-Origin` on the `POST` response as well:

* `Access-Control-Allow-Origin`: your application's origin
* `Access-Control-Allow-Methods`: `POST, OPTIONS`
* `Access-Control-Allow-Headers`: `Content-Type, Content-Encoding, Authorization`

## Server examples

Both examples satisfy every item in [Build your proxy](#build-your-proxy). Replace `eu1` with your own region.

### Node.js

This server has no dependencies and runs on Node.js 22 or later. It answers CORS preflights from the origins in `ALLOWED_ORIGINS`:

```
// In rum-proxy.mjs

// Relays Coralogix RUM SDK requests to the Coralogix ingress

import { createServer } from 'node:http';



const PORT = Number(process.env.PORT ?? 8080);

// Your Coralogix region's ingress, for example https://ingress.eu1.rum-ingress-coralogix.com

const INGRESS_URL = process.env.CORALOGIX_INGRESS_URL;

// Optional. When set, the proxy adds the key, so the page does not need to carry it.

const PUBLIC_KEY = process.env.CORALOGIX_PUBLIC_KEY;

// Comma-separated origins allowed to call the proxy, for example https://www.example.com.

// Not required when the proxy is served from the same origin as your application.

const ALLOWED_ORIGINS = new Set(

  (process.env.ALLOWED_ORIGINS ?? '')

    .split(',')

    .map((origin) => origin.trim())

    .filter(Boolean)

);



// The two endpoints the SDK sends to. The proxy forwards nothing else.

const CORALOGIX_PATHS = new Set([

  '/browser/v1beta/logs',

  '/browser/alpha/sessionrecording',

]);

const FORWARDED_HEADERS = ['content-type', 'content-encoding', 'authorization'];

const MAX_BODY_BYTES = 4 * 1024 * 1024;

const UPSTREAM_TIMEOUT_MS = 30_000;



if (!INGRESS_URL) {

  console.error('Set CORALOGIX_INGRESS_URL to your Coralogix ingress URL.');

  process.exit(1);

}



createServer(async (req, res) => {

  // 1. Answer the browser's CORS preflight, and refuse anything that is not a POST.

  setCorsHeaders(req, res);

  if (req.method === 'OPTIONS') return reply(res, 204);

  if (req.method !== 'POST') return reply(res, 405);



  // 2. Work out the Coralogix path from cxforward. A request including anything

  // other than the two SDK endpoints is rejected rather than forwarded.

  const path = coralogixPath(req.url);

  if (!path) return reply(res, 400);



  // 3. Buffer the body, rejecting anything over the size limit with 413.

  // The bytes are never decoded: a recording upload must reach Coralogix as it was sent.

  let body;

  try {

    body = await readBody(req);

  } catch {

    return reply(res, 413);

  }



  // 4. Relay the request to Coralogix and return its status code to the SDK.

  // A non-2xx on a recording upload stops Session Recording for that session.

  try {

    const upstream = await fetch(`${INGRESS_URL}${path}`, {

      method: 'POST',

      headers: upstreamHeaders(req),

      body,

      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),

    });

    // Read the whole response first. If it fails, the catch block can still send its own status code.

    const responseBody = Buffer.from(await upstream.arrayBuffer());

    res.writeHead(upstream.status, {

      'content-type': upstream.headers.get('content-type') ?? 'text/plain',

    });

    res.end(responseBody);

  } catch (error) {

    console.error('Forwarding to Coralogix failed:', error);

    reply(res, 502);

  }

}).listen(PORT, () => console.log(`RUM proxy listening on port ${PORT}`));



// The SDK sets the Coralogix endpoint in the `cxforward` query parameter. 

// Only its path is used. The host always comes from INGRESS_URL, so a caller cannot make the proxy send requests anywhere else. 

function coralogixPath(requestUrl) {

  try {

    const cxforward = new URL(requestUrl, 'http://proxy').searchParams.get('cxforward');

    if (!cxforward) return null;

    const { pathname } = new URL(cxforward);

    return CORALOGIX_PATHS.has(pathname) ? pathname : null;

  } catch {

    return null;

  }

}



function upstreamHeaders(req) {

  const headers = {};

  for (const name of FORWARDED_HEADERS) {

    if (req.headers[name]) headers[name] = req.headers[name];

  }

  if (PUBLIC_KEY) headers.authorization = `Bearer ${PUBLIC_KEY}`;



  // Read the client's address off the socket and append it to X-Forwarded-For,

  // preserving any addresses an upstream load balancer already set. Coralogix

  // locates the user from the first public address in that header. Node reports

  // IPv4 clients as ::ffff:a.b.c.d, which Coralogix does not read as public, so

  // strip the prefix.

  const clientIp = req.socket.remoteAddress?.replace(/^::ffff:/, '');

  headers['x-forwarded-for'] = [req.headers['x-forwarded-for'], clientIp]

    .filter(Boolean)

    .join(', ');

  return headers;

}



function readBody(req) {

  return new Promise((resolve, reject) => {

    const chunks = [];

    let size = 0;

    req.on('data', (chunk) => {

      size += chunk.length;

      if (size > MAX_BODY_BYTES) reject(new Error('Request body too large'));

      else chunks.push(chunk);

    });

    req.on('end', () => resolve(Buffer.concat(chunks)));

    req.on('error', reject);

  });

}



function setCorsHeaders(req, res) {

  const { origin } = req.headers;

  if (!origin || !ALLOWED_ORIGINS.has(origin)) return;

  res.setHeader('access-control-allow-origin', origin);

  res.setHeader('access-control-allow-methods', 'POST, OPTIONS');

  res.setHeader(

    'access-control-allow-headers',

    'Content-Type, Content-Encoding, Authorization'

  );

  res.setHeader('access-control-max-age', '86400');

  res.setHeader('vary', 'Origin');

}



function reply(res, status) {

  res.writeHead(status).end();

}
```

Run it with your region's ingress and your application's origin. To add the key on the proxy, also set `CORALOGIX_PUBLIC_KEY`:

```
CORALOGIX_INGRESS_URL=https://ingress.eu1.rum-ingress-coralogix.com \

ALLOWED_ORIGINS=https://www.example.com \

node rum-proxy.mjs
```

The server listens over plain HTTP, so run it behind the load balancer or ingress controller that terminates TLS for your domain. When that load balancer sets `X-Forwarded-For`, the proxy keeps the user's address from it and appends its own peer's address, which Coralogix skips because it is not public.

To deploy it as a container, build this image:

```
FROM node:24-alpine

WORKDIR /app

COPY rum-proxy.mjs .

USER node

EXPOSE 8080

CMD ["node", "rum-proxy.mjs"]
```

Build the image, then pass the same variables to the container. The proxy exits at startup when `CORALOGIX_INGRESS_URL` is unset:

```
docker build -t rum-proxy .



docker run -p 8080:8080 \

  -e CORALOGIX_INGRESS_URL=https://ingress.eu1.rum-ingress-coralogix.com \

  -e ALLOWED_ORIGINS=https://www.example.com \

  rum-proxy
```

### Nginx

When Nginx serves your application, add a location that relays to Coralogix from the same origin. Put the `map` block in the `http` context and the `location` block in your application's `server` block:

```
# Pick the Coralogix endpoint from the SDK's cxforward parameter. Nginx sees the parameter still URL-encoded, so match on how it ends.

map $arg_cxforward $coralogix_path {

    default                                     "";

    "~%2Fbrowser%2Fv1beta%2Flogs$"              /browser/v1beta/logs;

    "~%2Fbrowser%2Falpha%2Fsessionrecording$"   /browser/alpha/sessionrecording;

}



server {

    # ...your existing configuration for www.example.com...



    location = /rum {

        if ($coralogix_path = "") {

            return 400;

        }



        # Recording uploads can exceed the 1 MB default.

        client_max_body_size 4m;



        # Resolve the ingress at request time rather than once at startup.

        # Use your network's DNS resolver.

        resolver 8.8.8.8 valid=60s;

        set $coralogix_ingress ingress.eu1.rum-ingress-coralogix.com;



        proxy_pass https://$coralogix_ingress$coralogix_path;

        proxy_ssl_server_name on;

        proxy_ssl_verify on;

        proxy_ssl_verify_depth 2;

        # Your system's CA bundle. Debian, Ubuntu and Alpine use the path below;

        # RHEL and CentOS use /etc/pki/tls/certs/ca-bundle.crt.

        proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;



        # Nginx forwards the client's Authorization header by default.

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # Requests from your own origin carry your site's cookies. Do not send them on.

        proxy_set_header Cookie "";

        # Optional: add the key here and leave it out of the SDK's initialization.

        # proxy_set_header Authorization "Bearer <your public key>";

    }

}
```

Because `proxy_pass` names its target with variables, Nginx sends the request to the Coralogix path alone, without the `cxforward` parameter.

## Verify the setup

Make sure your proxy is reachable from the browser and that it forwards requests to Coralogix:

1. Load your application with the browser's developer tools open. On the **Network** tab, requests to your proxy's address carrying a `cxforward` parameter return `200`.
2. Confirm the data arrives in Coralogix. Select **RUM**, then **Sessions**, and find the session you just generated.
3. To test the proxy without a browser, send it an empty batch of events. A `200` response means the request reached Coralogix and the key was accepted. When the response code is `403`, the request doesn't have a key.

The command below carries the key itself. When your proxy adds the key instead, leave the `Authorization` header out:

```
curl -i -X POST \

  'https://www.example.com/rum?cxforward=https%3A%2F%2Fingress.eu1.rum-ingress-coralogix.com%2Fbrowser%2Fv1beta%2Flogs' \

  -H 'Content-Type: application/json' \

  -H 'Authorization: Bearer <public key>' \

  --data '{"logs":[]}'
```

## Troubleshooting

Several of the symptoms below surface as log output. The Browser SDK reports its own failures to the browser console, so open developer tools before you reproduce a problem. The other SDKs report theirs to their platform's log output, and most of them expose a `debug` option that raises the verbosity.

| Symptom                                                                                                | Cause                                                                                                               | What to do                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Every user is located wherever the proxy runs                                                          | The proxy does not append the client address to `X-Forwarded-For`                                                   | Append it. On Node.js, strip the `::ffff:` prefix that IPv4 clients arrive with, because Coralogix does not read that form as a public address                                                                            |
| The proxy returns `400` to every request                                                               | `proxyUrl` carries a query string of its own, so `cxforward` never arrives                                          | Remove the query string from `proxyUrl`                                                                                                                                                                                   |
| Session Recording stops a few seconds into a session                                                   | The proxy rejected a recording upload, most often on a body-size limit below 4 MB                                   | Raise the limit to at least 4 MB. A non-2xx response to a recording upload stops Session Recording for the rest of the session                                                                                            |
| Recordings arrive but do not play back                                                                 | The proxy decompressed the body of a [recording upload](#recording-uploads)                                         | Forward the body unchanged, along with `Content-Type` and `Content-Encoding`                                                                                                                                              |
| No requests reach the proxy, and the console reports a CORS error                                      | The proxy runs on its own origin and does not answer the preflight                                                  | Add the CORS response headers listed in [Where to host the proxy](#host-your-proxy)                                                                                                                                       |
| The console logs `rumAuth will be required in the future` on every page load                           | The public key is left out of the SDK's initialization so the proxy can add it                                      | Expected. Requests the proxy authenticates still reach Coralogix                                                                                                                                                          |
| The SDK never initializes and nothing reaches the proxy, and the console logs `Initialization aborted` | `coralogixDomain` is missing, or set to something other than a known region key, most often the region in lowercase | Set it to your region in uppercase, such as `EU1`. The region appears in lowercase only inside the ingress hostname. When your ingress is not one of the listed regions, set `coralogixDomainUrl` to the full URL instead |

## Learn more

* [RUM SDK installation](https://coralogix.com/docs/user-guides/rum/sdk-installation/overview.md)
* [Coralogix domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md)
* [Session Replay for web](https://coralogix.com/docs/user-guides/rum/product-features/session-replay/web.md)
* [Querying RUM logs](https://coralogix.com/docs/user-guides/rum/query-rum-logs.md)
