[{"data":1,"prerenderedAt":130},["ShallowReactive",2],{"doc:\u002Fdocs\u002Fproxy-integrations":3},{"page":4,"toc":122,"updated":129},{"path":5,"title":6,"seoTitle":7,"description":8,"blocks":9},"\u002Fdocs\u002Fproxy-integrations","Proxy integrations","Proxy Integrations: Serve Fingerly from Your Own Domain","Route the browser SDK through a path on your own domain so content blockers do not stop identification, without losing the visitor's real network signals.",[10,13,18,20,23,42,45,47,51,54,61,63,66,69,71,82,108,115,117,120],{"type":11,"text":12},"p","Content blockers and privacy extensions often refuse requests to third-party APIs. When they refuse Fingerly's, the visitor is simply not identified. A proxy integration sends the SDK's requests to a path on your own site instead, where they look like the rest of your traffic.",{"type":14,"level":15,"text":16,"id":17},"heading",2,"Why a Fingerly proxy is different","why-a-fingerly-proxy-is-different",{"type":11,"text":19},"A naive reverse proxy would make every visitor arrive from your server's address, and every network signal would describe your server rather than the visitor. A Fingerly proxy authenticates with a **proxy key**, and only then may it tell Fingerly the visitor's real address, origin and user agent. A public key alone can never do that, so nobody can spoof those details with your public key.",{"type":14,"level":15,"text":21,"id":22},"Options","options",{"type":24,"columns":25,"rows":29},"table",[26,27,28],"Option","Runs in","Best for",[30,34,38],[31,32,33],"[Cloudflare Worker](\u002Fdocs\u002Fsdks\u002Fcloudflare-worker)","Your Cloudflare account","Sites already on Cloudflare. No application changes.",[35,36,37],"[Node.js `createProxy`](\u002Fdocs\u002Fsdks\u002Fnode#serve-the-browser-sdk-from-your-domain)","Your application","Next.js, Remix, Hono, SvelteKit, Nuxt and any runtime with web `Request` and `Response`.",[39,40,41],"Your own proxy","Anywhere","Other stacks. Follow the contract below.",{"type":14,"level":15,"text":43,"id":44},"Proxy keys","proxy-keys",{"type":11,"text":46},"Proxy keys look like `fly_px_us_production_…`. Owners and admins issue them for one environment in **Integration > Proxy keys**, and each key is shown once, when it is issued. Only owners and admins can see and revoke them. A proxy key only forwards client requests: it cannot read events, and it must match the public key's organization, environment and region.",{"type":48,"tone":49,"text":50},"callout","warning","Store the proxy key as a server secret. Never ship it to browsers.",{"type":14,"level":15,"text":52,"id":53},"Point the SDK at your path","point-the-sdk-at-your-path",{"type":55,"samples":56},"code",[57],{"label":58,"lang":59,"code":60},"fingerly.ts","ts","import { load } from '@fingerly\u002Fweb-js'\n\nconst fingerly = await load({\n  apiKey: 'fly_pk_us_production_…',\n  endpoints: '\u002Fmetrics',                \u002F\u002F your proxy's path\n  fallbackToDefaultEndpoint: true,      \u002F\u002F optional: try Fingerly directly if the proxy fails\n})",{"type":11,"text":62},"The SDK appends `\u002Fapi\u002Fv1\u002Fidentify` to the path, and sends deferred reports to `\u002Fapi\u002Fv1\u002Fevents\u002F{request_id}\u002Fsupplement` under it. Omit `fallbackToDefaultEndpoint` to keep every request first-party.",{"type":48,"tone":64,"text":65},"tip","Choose a neutral path. Blockers look for words such as `fingerprint`, `tracking` and `fingerly`.",{"type":14,"level":15,"text":67,"id":68},"Build your own proxy","build-your-own-proxy",{"type":11,"text":70},"Forward only the two client routes, as `POST`, to your region's API, and replace the visitor headers with values you resolved yourself.",{"type":24,"columns":72,"rows":75},[73,74],"Incoming path","Forward to",[76,79],[77,78],"`{prefix}\u002Fapi\u002Fv1\u002Fidentify`","`https:\u002F\u002Fus.api.fingerly.io\u002Fapi\u002Fv1\u002Fidentify`",[80,81],"`{prefix}\u002Fapi\u002Fv1\u002Fevents\u002F{request_id}\u002Fsupplement`","`https:\u002F\u002Fus.api.fingerly.io\u002Fapi\u002Fv1\u002Fevents\u002F{request_id}\u002Fsupplement`",{"type":24,"columns":83,"rows":86},[84,85],"Header to send","Value",[87,90,93,96,99,102,105],[88,89],"`x-api-key`","The incoming `x-api-key` (the public key), unchanged.",[91,92],"`x-fingerly-proxy-key`","Your proxy key.",[94,95],"`x-fingerly-client-ip`","The visitor's IP address, from your load balancer or CDN.",[97,98],"`x-fingerly-origin`","The incoming `Origin`.",[100,101],"`x-fingerly-user-agent`","The incoming `User-Agent`.",[103,104],"`Idempotency-Key`","The incoming value, when present.",[106,107],"`Content-Type`","`application\u002Fjson`.",{"type":109,"items":110},"list",[111,112,113,114],"Do not forward cookies or `Authorization` headers, and strip `Set-Cookie` from responses.","Refuse other paths and methods, and cap request bodies at 1 MiB.","Do not follow redirects from the upstream.","Answer CORS preflights if the page and the proxy are on different origins.",{"type":48,"tone":49,"text":116},"Resolve the visitor's IP from infrastructure you control, such as `CF-Connecting-IP` behind Cloudflare. Never trust the left-most `X-Forwarded-For` value, which the visitor can write.",{"type":14,"level":15,"text":118,"id":119},"Data residency","data-residency",{"type":11,"text":121},"A proxy never changes where data goes. The region is part of both keys, and a request forwarded to another region's API is refused.",[123,124,125,126,127,128],{"id":17,"text":16,"level":15},{"id":22,"text":21,"level":15},{"id":44,"text":43,"level":15},{"id":53,"text":52,"level":15},{"id":68,"text":67,"level":15},{"id":119,"text":118,"level":15},"2026-09-17T16:57:42.000Z",1789667797515]