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

# Route an integration through your own API proxy

> Keep your real vendor keys in a proxy you host, give Neo placeholders, and cut Neo's calls to a vendor at your proxy.

Neo normally holds your vendor keys and calls the vendor directly. With an API proxy route, Neo sends one integration's calls to a reverse proxy you run, such as a Cloudflare Worker. The proxy holds the real keys and Neo stores only placeholders. If Neo were ever breached, the attacker would find no key that works anywhere else, and you can log, filter and stop every Neo call at your proxy.

The [emergency stop](https://docs.neoagent.io/product/emergency-stop.md) stops Neo from inside Neo. A proxy route is the switch you hold outside it.

## How a routed call travels

When you route an integration, Neo changes only where its calls go:

```
https://api.huntress.io/v1/agents?page=2
→ https://neo-proxy.example.com/neo/api.huntress.io/v1/agents?page=2
```

The vendor's host becomes the first part of the path after your proxy URL, so one proxy serves every vendor. Each call carries the [authentication headers](#how-neo-authenticates-to-your-proxy) your proxy checks, and the vendor's keys travel exactly as they always do, but as placeholders. Your proxy checks the headers, swaps the placeholders for the real keys and sends the call on.

For example, a Huntress call. Huntress authenticates with `Authorization: Basic`, the base64 of `<API Key>:<API Secret>`. Neo stores the placeholder `neoproxy_huntress_api_secret` in place of the API Secret, so it sends:

```
GET https://neo-proxy.example.com/neo/api.huntress.io/v1/agents
X-Neo-Proxy-Key: <your proxy's secret>
Authorization: Basic base64("<API Key>:neoproxy_huntress_api_secret")
```

Your proxy checks and removes `X-Neo-Proxy-Key`, decodes the Basic value, replaces the placeholder with the real API Secret, encodes it again, and sends:

```
GET https://api.huntress.io/v1/agents
Authorization: Basic base64("<API Key>:<your real API Secret>")
```

Each integration's **Setup** tab shows the same example for that integration, with your proxy URL filled in.

Links the vendor returns, such as the next page of a list, come back through the same route.

## Integrations you can route

| Integration | Vendor hosts | Placeholder Neo sends | Where your proxy swaps it |
| - | - | - | - |
| Datto RMM | `*.centrastage.net` | `neoproxy_datto_rmm_api_secret` | The `password` form field of `POST /auth/oauth/token` |
| IT Glue | `api.itglue.com`, `api.eu.itglue.com`, `api.au.itglue.com` | `neoproxy_itglue_api_key` | The `x-api-key` header of every call |
| Huntress | `api.huntress.io` | `neoproxy_huntress_api_secret` | `Authorization: Basic`, inside the base64 value |
| AbuseIPDB | `api.abuseipdb.com` | `neoproxy_abuseipdb_api_key` | The `Key` header of every call |
| ConnectWise CPQ | `sellapi.quosalsell.com` | `neoproxy_connectwise_cpq_private_key` | `Authorization: Basic`, inside the base64 value |
| Ingram Micro Cloud Marketplace | `api.cloud.im` | `neoproxy_ingram_micro_password` and `neoproxy_ingram_micro_subscription_key` | `Authorization: Basic` on the token call, and the `X-Subscription-Key` header of every call |

The integration's **Setup** tab shows the same facts for that integration, with its entries for the reference Worker ready to copy.

Keep each vendor's own URL in its Setup fields (the Datto RMM URL, the IT Glue API URL, the Ingram Micro API URL). Neo routes calls by the vendor's host, so a URL on another host is not routed.

## Set it up

**1. Deploy your proxy**

Deploy the [reference Worker](#reference-cloudflare-worker) below, or your own proxy that follows the same contract. Give it your real vendor keys as secrets, a recipe for each vendor you route, and the check of Neo's authentication headers.

**2. Turn on the proxy in Neo**

Open the integration in [**Integrations**](https://dashboard.neoagent.io/integrations). On its **Setup** tab, turn on **Send … calls through your own API proxy**. Enter your **Proxy URL**, pick how your proxy checks it is Neo, and enter the header values. Only an Owner or Admin can do this.

The vendor's secret fields leave the form while the switch is on: Neo stores the placeholders there itself. The other fields, such as the Huntress API Key or the Datto RMM URL, stay.

**3. Save**

Neo first checks the connection through your proxy, with the placeholders, before it stores anything. If the check passes, Neo replaces the stored keys with the placeholders and turns the route on. If it fails, for example because your proxy is unreachable, refuses Neo's headers, or the vendor rejects the key after the swap, nothing changes: the integration keeps working directly, and the error says which step failed.

Every owner and admin gets an email when someone sets, changes or removes a route, and the change goes on that person's Activity History. New header values on the same proxy URL keep the placeholders. A new proxy URL deletes the keys again.

To stop routing, turn the switch off, type the vendor's real keys in the fields that come back, and save. Neo checks the real keys directly first; only when that passes does it store them and remove the route.

Neo also refuses to send a call to your proxy that would carry a real key of that integration, so a real key never reaches a proxy, even for a moment during a change.

## How Neo authenticates to your proxy

Proxies check different headers, so you name them: one to three headers, each a name and a secret value. One value must be at least 24 characters with no spaces. Neo never sends a name the vendor's own calls use, such as `Authorization`, and refuses one when you save.

| Your proxy | Headers to send |
| - | - |
| The reference Worker, NGINX, Caddy, HAProxy, Traefik ForwardAuth, or any proxy that checks a header you choose | `X-Neo-Proxy-Key` |
| Cloudflare Access service token | `CF-Access-Client-Id` and `CF-Access-Client-Secret` |
| Azure API Management subscription key | `Ocp-Apim-Subscription-Key`, or the header name you set on the API |
| AWS API Gateway API key | `X-API-Key`. IT Glue uses the same header for its own key, so route IT Glue through a Lambda authorizer with another header name |

An IP allowlist alone does not protect your proxy: every Neo customer sends from the same [IP addresses](https://docs.neoagent.io/integrations/ip-whitelisting.md), so another Neo account could name your proxy URL. Use it beside a header, as the reference Worker's `NEO_IPS` does.

The [public API](https://docs.neoagent.io/developers/introduction.md) lists the routes at `GET /public-api/integrations/api-proxy`. Only a signed-in admin or owner changes a route, so that the change goes on their Activity History: use the switch on the integration's Setup tab. An API key cannot set or remove a route. The Neo Support Agent can show your routes and remove one after you approve, and it never sets a route, because the header values would pass through the chat.

## Reference Cloudflare Worker

This Worker:

* refuses every call while `KILL_SWITCH` is `on`, so one setting cuts Neo off from every routed vendor
* checks the `X-Neo-Proxy-Key` header against your secret
* optionally accepts calls only from [Neo's IP addresses](https://docs.neoagent.io/integrations/ip-whitelisting.md)
* serves only the vendor hosts in its recipes, so it is no open proxy
* swaps a placeholder only where the recipe says, so a ticket note that quotes a placeholder never receives a real key
* keeps a vendor's redirect on the proxy when it points at a host the Worker serves, and passes any other redirect back unchanged
* logs each call's method, vendor host, path and status

Set these in the Worker's **Settings** → **Variables and Secrets**:

| Name | Type | Value |
| - | - | - |
| `NEO_PROXY_KEY` | Secret | The `X-Neo-Proxy-Key` value you enter in Neo |
| `KILL_SWITCH` | Text | `on` to refuse every call; anything else to serve |
| `PATH_PREFIX` | Text | The path of your proxy URL, such as `/neo`, or empty |
| `NEO_IPS` | Text | Optional. Neo's IP addresses, comma-separated |
| `RECIPES` | Text | The JSON below |
| One per real key | Secret | The names your recipes give, such as `NEOPROXY_HUNTRESS_API_SECRET` |

A recipe names, per vendor host, the placeholders it swaps and where: `headers` (header names), `basic` (inside `Authorization: Basic`), `query` (query parameter names) and `bodyPaths` (paths of token or login calls whose form or JSON body holds a placeholder).

```json RECIPES theme={null}
{
  "*.centrastage.net": {"secrets": {"neoproxy_datto_rmm_api_secret": "NEOPROXY_DATTO_RMM_API_SECRET"}, "bodyPaths": ["/auth/oauth/token"]},
  "api.itglue.com": {"secrets": {"neoproxy_itglue_api_key": "NEOPROXY_ITGLUE_API_KEY"}, "headers": ["x-api-key"]},
  "api.eu.itglue.com": {"secrets": {"neoproxy_itglue_api_key": "NEOPROXY_ITGLUE_API_KEY"}, "headers": ["x-api-key"]},
  "api.au.itglue.com": {"secrets": {"neoproxy_itglue_api_key": "NEOPROXY_ITGLUE_API_KEY"}, "headers": ["x-api-key"]},
  "api.huntress.io": {"secrets": {"neoproxy_huntress_api_secret": "NEOPROXY_HUNTRESS_API_SECRET"}, "basic": true},
  "api.abuseipdb.com": {"secrets": {"neoproxy_abuseipdb_api_key": "NEOPROXY_ABUSEIPDB_API_KEY"}, "headers": ["Key"]},
  "sellapi.quosalsell.com": {"secrets": {"neoproxy_connectwise_cpq_private_key": "NEOPROXY_CONNECTWISE_CPQ_PRIVATE_KEY"}, "basic": true},
  "api.cloud.im": {"secrets": {"neoproxy_ingram_micro_password": "NEOPROXY_INGRAM_MICRO_PASSWORD", "neoproxy_ingram_micro_subscription_key": "NEOPROXY_INGRAM_MICRO_SUBSCRIPTION_KEY"}, "headers": ["X-Subscription-Key"], "basic": true}
}
```

```js neo-proxy.js theme={null}
// Neo API proxy: a reference Cloudflare Worker.
// Neo sends each call for a routed integration to
//   https://<this worker><PATH_PREFIX>/<vendor host>/<path>?<query>
// with the header X-Neo-Proxy-Key.

const MAX_SWAPPED_BODY_BYTES = 65536;
const HOST_SHAPE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
const DROPPED_HEADERS = ["x-neo-proxy-key", "host", "cf-connecting-ip", "cf-ipcountry", "cf-ray", "cf-visitor",
  "x-forwarded-for", "x-forwarded-proto", "x-real-ip", "content-length"];

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const refuse = (status, reason, host) => {
      console.log(JSON.stringify({ method: request.method, host, status, refused: reason }));
      return new Response(reason, { status });
    };
    if (env.KILL_SWITCH === "on") return refuse(503, "The proxy is switched off.");
    if (!(await keyMatches(request.headers.get("X-Neo-Proxy-Key"), env.NEO_PROXY_KEY))) return refuse(401, "Wrong proxy key.");
    if (env.NEO_IPS) {
      const allowed = env.NEO_IPS.split(",").map((ip) => ip.trim());
      if (!allowed.includes(request.headers.get("CF-Connecting-IP"))) return refuse(403, "Caller is not Neo.");
    }

    const prefix = (env.PATH_PREFIX || "").replace(/\/+$/, "");
    if (!url.pathname.startsWith(`${prefix}/`)) return refuse(404, "Unknown path.");
    const rest = url.pathname.slice(prefix.length + 1);
    const slash = rest.indexOf("/");
    const host = (slash === -1 ? rest : rest.slice(0, slash)).toLowerCase();
    const path = slash === -1 ? "/" : rest.slice(slash);
    const recipes = JSON.parse(env.RECIPES);
    const recipe = HOST_SHAPE.test(host) ? recipeFor(recipes, host) : null;
    if (!recipe) return refuse(403, "Vendor host not allowed.", host);
    const upstream = new URL(`https://${host}${path}${url.search}`);
    if (upstream.hostname !== host || upstream.port !== "") return refuse(403, "Vendor host not allowed.", host);

    const secrets = secretsFor(recipe, env);
    for (const name of recipe.query || []) {
      const value = upstream.searchParams.get(name);
      if (value !== null) upstream.searchParams.set(name, swap(value, secrets));
    }
    const headers = new Headers(request.headers);
    for (const name of DROPPED_HEADERS) headers.delete(name);
    for (const name of recipe.headers || []) {
      const value = headers.get(name);
      if (value !== null) headers.set(name, swap(value, secrets));
    }
    const authorization = headers.get("Authorization");
    if (recipe.basic && authorization && authorization.startsWith("Basic ")) {
      headers.set("Authorization", `Basic ${btoa(swap(atob(authorization.slice(6)), secrets))}`);
    }

    let body = ["GET", "HEAD"].includes(request.method) ? undefined : await request.arrayBuffer();
    if (body !== undefined && (recipe.bodyPaths || []).includes(path)) {
      if (body.byteLength > MAX_SWAPPED_BODY_BYTES) return refuse(413, "Body too large.", host);
      body = swapBody(new TextDecoder().decode(body), headers.get("Content-Type") || "", secrets);
    }

    const answer = await fetch(upstream, { method: request.method, headers, body, redirect: "manual" });
    const response = new Response(answer.body, answer);
    const location = answer.headers.get("Location");
    if (location) response.headers.set("Location", proxiedLocation(location, upstream, `${url.origin}${prefix}`, recipes));
    console.log(JSON.stringify({ method: request.method, host, path, status: answer.status }));
    return response;
  },
};

async function keyMatches(sent, expected) {
  if (!sent || !expected) return false;
  const a = new TextEncoder().encode(sent);
  const b = new TextEncoder().encode(expected);
  if (a.byteLength !== b.byteLength) return false;
  return crypto.subtle.timingSafeEqual(a, b);
}

function hostMatches(host, pattern) {
  if (pattern.startsWith("*.")) return host.endsWith(pattern.slice(1)) && host.length > pattern.length - 1;
  return host === pattern;
}

function recipeFor(recipes, host) {
  const pattern = Object.keys(recipes).find((candidate) => hostMatches(host, candidate));
  return pattern === undefined ? null : recipes[pattern];
}

function secretsFor(recipe, env) {
  const pairs = Object.entries(recipe.secrets || {}).map(([placeholder, name]) => [placeholder, env[name]]);
  const missing = pairs.filter(([, value]) => typeof value !== "string" || value === "");
  if (missing.length) throw new Error(`Set the Worker secret for ${missing.map(([placeholder]) => placeholder).join(", ")}.`);
  return pairs;
}

function swap(text, secrets) {
  return secrets.reduce((value, [placeholder, real]) => value.split(placeholder).join(real), text);
}

function swapBody(text, contentType, secrets) {
  if (contentType.includes("application/x-www-form-urlencoded")) {
    const form = new URLSearchParams(text);
    for (const [name, value] of [...form.entries()]) form.set(name, swap(value, secrets));
    return form.toString();
  }
  if (contentType.includes("json")) {
    return JSON.stringify(JSON.parse(text), (key, value) => (typeof value === "string" ? swap(value, secrets) : value));
  }
  return text;
}

// A redirect to a host this Worker serves stays on the proxy, in the form Neo uses. Any other
// Location goes back unchanged, and Neo drops its keys when it follows a redirect to another origin.
function proxiedLocation(location, upstream, proxyBase, recipes) {
  const target = new URL(location, upstream);
  if (target.protocol !== "https:" || target.port !== "" || !recipeFor(recipes, target.hostname)) return location;
  return `${proxyBase}/${target.hostname}${target.pathname}${target.search}`;
}
```

## What a route protects, and what it does not

* **A breach of Neo yields no working vendor key.** It still yields your proxy URL, your authentication header values and the placeholders, so an attacker who controls Neo could call your vendors through your proxy until you switch it off. The `NEO_IPS` check limits such calls to Neo's own addresses, and your proxy's log shows each one.
* **A token Neo gets through the proxy is real.** For Datto RMM and Ingram Micro, the token call goes through your proxy, and the vendor answers with a short-lived access token that Neo then holds until it expires.
* **Vendors that allowlist Neo's IP addresses see your proxy's address instead.** A Cloudflare Worker calls vendors from Cloudflare's shared addresses. If a vendor accepts only listed addresses, run your proxy where it has fixed outbound addresses and list those at the vendor, or keep that vendor off the proxy.
* **A [customer's own key](https://docs.neoagent.io/integrations/customer-credentials.md) goes to the vendor directly.** The route carries your own connection to the vendor. Neo stores a customer's own key and checks it as it always did.
* **A route change reaches new runs within about 10 seconds.** A run already going keeps the route it started with.

## Integrations a proxy cannot cover

Some integrations hold no key you type in Neo, or send it to a host other integrations share. Cut those at the vendor:

* **Microsoft 365, Microsoft Graph and Exchange Online**: Neo calls Microsoft with its own app and your consent. Remove or disable the Neo app in Microsoft Entra to cut it.
* **NinjaOne, Xero and QuickBooks Online**: Neo holds a token from the sign-in you approved. Revoke Neo's access in the vendor's app settings.
* **Autotask**: every Autotask call carries Neo's own Autotask integration code, which your proxy would see, so Neo does not route Autotask. Cut it at Autotask: set Neo's API user to inactive.
* **CIPP**: its client secret goes to Microsoft's sign-in service, which Neo cannot route per integration. Rotate or remove the CIPP app's client secret in your own Entra to cut it. Its API URL field already accepts a proxy address for the API calls themselves.


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