> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openrevenue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# First-party proxy

> Serve the OpenRevenue tracker and send its events through your own domain, so ad blockers don't drop them and visitor locations stay correct.

A first-party proxy is a small piece of code on your own server. It serves the tracker from your domain and forwards its events to OpenRevenue:

| Your site | Forwards to |
| - | - |
| `GET /or/s.js` | `https://api.openrevenue.com/tracker.js` |
| `POST /or/e` | `https://api.openrevenue.com/api/track` |
| `GET /or/check` | `https://api.openrevenue.com/api/proxy/check` (setup check) |

Every other path under `/or/` returns `404`.

## Why use it

* **Ad blockers.** Many blocklists match requests to analytics domains. Requests to your own domain at `/or/` are not on those lists, so fewer pageviews go missing.
* **Correct visitor location.** Without a key, OpenRevenue would see your server's address instead of your visitor's. The proxy sends a key, the visitor's address and, where your platform provides it, the visitor's location. OpenRevenue uses them only when the key is valid for the project.

The proxy does not change how long OpenRevenue recognises a returning visitor. The tracker stores its visitor ID in the browser exactly as it does without a proxy.

## How it works

1. The browser loads `/or/s.js` from your site. Your proxy fetches it from OpenRevenue.
2. The tracker sees that it was loaded from `/or/s.js` and sends events to `/or/e` next to it, on your domain.
3. Your proxy forwards each event to OpenRevenue with your proxy key and the visitor's address and location.
4. OpenRevenue checks the key. If it's valid for the project, it records the forwarded address and location. If it isn't, the event is still counted, but without the visitor's address and location. All visitors then share your server's address, so on a busy site per-address rate limits can start dropping events: keep the key valid.

## Set it up

**1. Create a proxy key**

Open `Settings → Proxy` for your project and click **Create proxy key**. Copy the key: it starts with `orpx_` and is shown only once. OpenRevenue stores only a hash of it.

Only project owners and admins can create, rotate or remove keys.

**2. Add the proxy to your site**

Pick the recipe for your platform [below](#recipes) and paste it as-is. Store the key on the server only. It must never appear in your HTML or JavaScript.

**3. Change the script tag**

Load the tracker from your own domain:

```html theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
<script defer src="/or/s.js" data-site="your-project-id"></script>
```

Replace `your-project-id` with the project ID from `Settings → General`. You don't need any other attribute: events go to `/or/e` automatically.

**4. Check the setup**

In `Settings → Proxy`, under **Check proxy**, enter your proxy address (for example `https://example.com/or`) and click **Check**. OpenRevenue loads `/or/s.js` and calls `/or/check` through your proxy, then shows whether the key is valid and whether the visitor's address and location arrive. No event is recorded. See [Check the proxy](#check).

## Recipes

Each recipe is one file with no dependencies. They forward only the browser headers OpenRevenue needs (see [What the proxy forwards](#forwarded)).

> [tab] Next.js
>
> For the App Router in Next.js 15 and 16, on Vercel or any other host. Save the file as `app/or/[...path]/route.ts` (or `src/app/or/[...path]/route.ts` if you use a `src` folder).
>
> Set `OPENREVENUE_PROXY_KEY` in your server environment, for example in your Vercel project settings. Don't prefix it with `NEXT_PUBLIC_`: that would publish it in your JavaScript.
>
> ```ts app/or/[...path]/route.ts theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
> // OpenRevenue first-party proxy for Next.js (App Router, Next.js 15 or later).
> // Save as app/or/[...path]/route.ts
> //
> // Serves the tracker at /or/s.js and forwards its events from /or/e, so
> // analytics requests stay on your domain. Set OPENREVENUE_PROXY_KEY in your
> // server environment. Never prefix it with NEXT_PUBLIC_: it must not reach
> // the browser.
>
> const COLLECTOR = process.env.OPENREVENUE_COLLECTOR_ORIGIN || "https://api.openrevenue.com"
>
> // The only browser headers sent on. Cookies and Authorization never leave your site.
> const FORWARD = [
>   "content-type",
>   "user-agent",
>   "accept-language",
>   "origin",
>   "referer",
>   "sec-fetch-site",
>   "sec-fetch-mode",
>   "sec-fetch-dest",
>   "sec-gpc",
> ]
>
> // Location headers Vercel adds to each request, and the names OpenRevenue reads.
> const VERCEL_GEO: [string, string][] = [
>   ["x-vercel-ip-country", "x-openrevenue-geo-country"],
>   ["x-vercel-ip-country-region", "x-openrevenue-geo-region"],
>   ["x-vercel-ip-city", "x-openrevenue-geo-city"],
>   ["x-vercel-ip-latitude", "x-openrevenue-geo-latitude"],
>   ["x-vercel-ip-longitude", "x-openrevenue-geo-longitude"],
> ]
>
> type Context = { params: Promise<{ path?: string[] }> }
>
> export async function GET(request: Request, { params }: Context) {
>   const path = (await params).path?.join("/")
>   if (path === "s.js") {
>     // The script is the same for every visitor, so cache it for an hour.
>     return relay(await fetch(COLLECTOR + "/tracker.js", { next: { revalidate: 3600 } }))
>   }
>   if (path === "check") {
>     return forward(request, COLLECTOR + "/api/proxy/check" + new URL(request.url).search)
>   }
>   return new Response("Not found", { status: 404 })
> }
>
> export async function POST(request: Request, { params }: Context) {
>   if ((await params).path?.join("/") !== "e") return new Response("Not found", { status: 404 })
>   return forward(request, COLLECTOR + "/api/track", await request.text())
> }
>
> async function forward(request: Request, url: string, body?: string) {
>   const headers = new Headers()
>   for (const name of FORWARD) {
>     const value = request.headers.get(name)
>     if (value) headers.set(name, value)
>   }
>   // The key tells OpenRevenue to trust the address and location below.
>   headers.set("x-openrevenue-proxy-key", process.env.OPENREVENUE_PROXY_KEY ?? "")
>   headers.set("x-openrevenue-proxy", "nextjs/1")
>   // The visitor's address, as your host reports it.
>   const ip =
>     request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
>     request.headers.get("x-real-ip")
>   if (ip) headers.set("x-openrevenue-client-ip", ip)
>   // On Vercel, also pass on the visitor's location.
>   if (process.env.VERCEL) {
>     for (const [from, to] of VERCEL_GEO) {
>       const value = request.headers.get(from)
>       if (value) headers.set(to, value)
>     }
>   }
>   return relay(await fetch(url, { method: request.method, headers, body, cache: "no-store" }))
> }
>
> // Send back the status, body and these two headers only (never Set-Cookie).
> function relay(upstream: Response) {
>   const headers = new Headers()
>   for (const name of ["content-type", "cache-control"]) {
>     const value = upstream.headers.get(name)
>     if (value) headers.set(name, value)
>   }
>   return new Response(upstream.body, { status: upstream.status, headers })
> }
> ```
>
> * **Visitor address:** the first entry of `x-forwarded-for`, or `x-real-ip`, as your host sets them.
> * **Location:** on Vercel, from Vercel's `x-vercel-ip-*` headers. On other hosts, events are recorded without a location.
> * **Caching:** the script is cached for an hour. Events and checks are never cached.
> * **Self-hosted OpenRevenue:** set `OPENREVENUE_COLLECTOR_ORIGIN` to your OpenRevenue address.

> [tab] Cloudflare Worker
>
> For any site whose domain is on Cloudflare. Create a Worker with this code, add the route `example.com/or/*` (with your domain), and store the key as a secret:
>
> ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
> npx wrangler secret put OPENREVENUE_PROXY_KEY
> ```
>
> You can also add the secret in the Cloudflare dashboard under the Worker's **Settings → Variables and Secrets**.
>
> ```js worker.js theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
> // OpenRevenue first-party proxy for Cloudflare Workers.
> // Add a route for example.com/or/* to this Worker, and store the key as a secret:
> //   npx wrangler secret put OPENREVENUE_PROXY_KEY
> //
> // Serves the tracker at /or/s.js and forwards its events from /or/e, so
> // analytics requests stay on your domain.
>
> const PREFIX = "/or"
>
> // The only browser headers sent on. Cookies and Authorization never leave your site.
> const FORWARD = [
>   "content-type",
>   "user-agent",
>   "accept-language",
>   "origin",
>   "referer",
>   "sec-fetch-site",
>   "sec-fetch-mode",
>   "sec-fetch-dest",
>   "sec-gpc",
> ]
>
> export default {
>   async fetch(request, env) {
>     const collector = env.OPENREVENUE_COLLECTOR_ORIGIN || "https://api.openrevenue.com"
>     const url = new URL(request.url)
>     const path = url.pathname.startsWith(PREFIX + "/") ? url.pathname.slice(PREFIX.length) : ""
>
>     if (request.method === "GET" && path === "/s.js") {
>       // The script is the same for every visitor, so cache it for an hour.
>       return relay(await fetch(collector + "/tracker.js", { cf: { cacheTtl: 3600, cacheEverything: true } }))
>     }
>     if (request.method === "GET" && path === "/check") {
>       return forward(request, env, collector + "/api/proxy/check" + url.search)
>     }
>     if (request.method === "POST" && path === "/e") {
>       return forward(request, env, collector + "/api/track", await request.text())
>     }
>     if (request.method === "OPTIONS" && path === "/e") {
>       // Same-origin requests do not need this; answer here instead of forwarding.
>       return new Response(null, { status: 204, headers: { Allow: "POST, OPTIONS" } })
>     }
>     return new Response("Not found", { status: 404 })
>   },
> }
>
> async function forward(request, env, url, body) {
>   const headers = new Headers()
>   for (const name of FORWARD) {
>     const value = request.headers.get(name)
>     if (value) headers.set(name, value)
>   }
>   // The key tells OpenRevenue to trust the address and location below.
>   headers.set("x-openrevenue-proxy-key", env.OPENREVENUE_PROXY_KEY || "")
>   headers.set("x-openrevenue-proxy", "cloudflare/1")
>   // The visitor's address and location, as Cloudflare sees them.
>   const ip = request.headers.get("cf-connecting-ip")
>   if (ip) headers.set("x-openrevenue-client-ip", ip)
>   const cf = request.cf || {}
>   if (cf.country) headers.set("x-openrevenue-geo-country", cf.country)
>   if (cf.regionCode) headers.set("x-openrevenue-geo-region", cf.regionCode)
>   if (cf.city) headers.set("x-openrevenue-geo-city", encodeURIComponent(cf.city))
>   if (cf.latitude) headers.set("x-openrevenue-geo-latitude", String(cf.latitude))
>   if (cf.longitude) headers.set("x-openrevenue-geo-longitude", String(cf.longitude))
>   return relay(await fetch(url, { method: request.method, headers, body }))
> }
>
> // Send back the status, body and these two headers only (never Set-Cookie).
> function relay(upstream) {
>   const headers = new Headers()
>   for (const name of ["content-type", "cache-control"]) {
>     const value = upstream.headers.get(name)
>     if (value) headers.set(name, value)
>   }
>   return new Response(upstream.body, { status: upstream.status, headers })
> }
> ```
>
> * **Visitor address:** from `CF-Connecting-IP`.
> * **Location:** country, region, city and coordinates from Cloudflare (`request.cf`).
> * **Caching:** the script is cached at Cloudflare for an hour. Events and checks are never cached.
> * **Self-hosted OpenRevenue:** set `OPENREVENUE_COLLECTOR_ORIGIN` to your OpenRevenue address.

> [tab] nginx
>
> Paste this inside your site's `server { }` block and reload nginx.
>
> nginx can't read environment variables in this configuration, so the key is written into the file. Replace `YOUR_PROXY_KEY` with your key and keep the file readable only by root. You can also put the key line in a separate root-only file and `include` it.
>
> ```nginx nginx.conf theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
> # OpenRevenue first-party proxy for nginx.
> # Paste inside your site's server { } block, then reload nginx.
> #
> # nginx cannot read environment variables here, so the key is written into
> # this file: replace YOUR_PROXY_KEY with the key from Project settings → Proxy
> # and keep the file private. (You can also move that one line into a file
> # only root can read and include it.)
>
> location /or/ {
>     # Send on only the browser headers OpenRevenue needs.
>     proxy_pass_request_headers off;
>     proxy_set_header content-type $http_content_type;
>     proxy_set_header user-agent $http_user_agent;
>     proxy_set_header accept-language $http_accept_language;
>     proxy_set_header origin $http_origin;
>     proxy_set_header referer $http_referer;
>     proxy_set_header sec-fetch-site $http_sec_fetch_site;
>     proxy_set_header sec-fetch-mode $http_sec_fetch_mode;
>     proxy_set_header sec-fetch-dest $http_sec_fetch_dest;
>     proxy_set_header sec-gpc $http_sec_gpc;
>     # Cookies and Authorization never leave your site.
>     proxy_set_header Cookie "";
>     proxy_set_header Authorization "";
>
>     # The key tells OpenRevenue to trust the address below.
>     proxy_set_header x-openrevenue-proxy-key "YOUR_PROXY_KEY";
>     proxy_set_header x-openrevenue-proxy "nginx/1";
>     # The visitor's address. Behind a load balancer or Cloudflare, $remote_addr
>     # is the balancer: set up the real_ip module, or use $http_cf_connecting_ip
>     # behind Cloudflare.
>     proxy_set_header x-openrevenue-client-ip $remote_addr;
>     # Behind Cloudflare only: pass on the visitor's country.
>     # proxy_set_header x-openrevenue-geo-country $http_cf_ipcountry;
>
>     proxy_set_header Host api.openrevenue.com;
>     proxy_http_version 1.1;
>     proxy_ssl_server_name on;
>     # Never pass cookies back to the browser.
>     proxy_hide_header Set-Cookie;
>
>     location = /or/s.js { proxy_pass https://api.openrevenue.com/tracker.js; }
>     location = /or/e { proxy_pass https://api.openrevenue.com/api/track; }
>     location = /or/check { proxy_pass https://api.openrevenue.com/api/proxy/check; }
>
>     # Anything else under /or/ does not exist.
>     return 404;
> }
> ```
>
> * **Visitor address:** `$remote_addr`. If nginx runs behind a load balancer or Cloudflare, `$remote_addr` is the balancer's address. Set up the [real IP module](https://nginx.org/en/docs/http/ngx_http_realip_module.html), or use `$http_cf_connecting_ip` behind Cloudflare.
> * **Location:** nginx has no location data of its own. Behind Cloudflare, uncomment the `CF-IPCountry` line to send the visitor's country. Otherwise events are recorded without a location.
> * **Caching:** nginx passes on OpenRevenue's `Cache-Control` header, so browsers cache the script for an hour.

## Check the proxy

**Check proxy** in `Settings → Proxy` runs this check for you. You can also call it yourself:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
curl "https://example.com/or/check?site=your-project-id"
```

A working proxy returns:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "collector": "openrevenue",
  "siteFound": true,
  "key": "valid",
  "clientIpForwarded": true,
  "locationForwarded": true,
  "recipe": "nextjs/1"
}
```

| Field | Meaning |
| - | - |
| `siteFound` | `false` if no project has this ID. |
| `key` | `valid`, `invalid` (wrong, revoked or empty key), or `missing` (the request didn't come through a proxy). |
| `clientIpForwarded` | A public visitor address arrived. Your own address when you run `curl`. |
| `locationForwarded` | A visitor country arrived. Expected to be `false` for nginx without Cloudflare and for Next.js outside Vercel. |
| `recipe` | Which recipe the proxy reports, for example `cloudflare/1`. |

If `key` is `invalid`, check that the environment variable or placeholder holds the full key and that you redeployed after changing it.

## Rotate or remove the key

* **Rotate:** `Settings → Proxy` → **Rotate key** creates a new key. The old key keeps working for 24 hours, so you have time to deploy the new one.
* **Rotate and revoke:** the old key stops working immediately. Use this if the key leaked.
* **Remove:** every key for the project stops working.

While a proxy sends a key that isn't valid, its events are still counted, but OpenRevenue ignores the forwarded address and location: it sees your server's address and records no location.

## What the proxy forwards

To OpenRevenue, the proxy sends:

* The event body, unchanged.
* These browser headers, unchanged: `Content-Type`, `User-Agent`, `Accept-Language`, `Origin`, `Referer`, `Sec-Fetch-Site`, `Sec-Fetch-Mode`, `Sec-Fetch-Dest` and `Sec-GPC`.
* Your proxy key, the visitor's address, the visitor's location if your platform knows it, and the recipe name.

It never sends cookies, `Authorization` headers or any other request header.

Back to the browser, the proxy returns only the status, the body, `Content-Type` and `Cache-Control`. It never passes on `Set-Cookie`.

## Limits

* Without a valid key, OpenRevenue can't trust the forwarded address, so it records your server's address and no location.
* nginx without Cloudflare in front, and Next.js outside Vercel, can't send a location. Events are counted without one.
* The proxy must be on the same site as your pages. OpenRevenue still checks the `Origin` of each event against your project's [allowed hostnames](https://docs.openrevenue.com/advanced/security.md).
* If you use a different path than `/or/`, change it in the recipe and in the script `src`. The tracker always sends events to `e` next to the script, for example `/stats/e` for `/stats/s.js`. To send events somewhere else, set `data-api` on the script tag to the full event URL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.