Copy page

Guides

How to check an incoming IP address

To get the IP address of the client that made the current request, read it from the request context:

Code
export default async function (request: ZuploRequest, context: ZuploContext) {
  const ip = context.incomingRequestProperties.ip;
  return new Response(ip ?? "unknown");
}

This is the official way to read the client IP. Zuplo resolves the address from the layer in front of your gateway, so you get the same property regardless of where the gateway runs.

Handle an unknown address

The value is undefined when nothing identified the caller. Handle that case explicitly:

Code
const ip = context.incomingRequestProperties.ip;
if (!ip) {
  return HttpProblems.badRequest(request, context, {
    detail: "Could not determine the client IP address",
  });
}

Don't substitute a placeholder such as "unknown" or 0.0.0.0 and then key on it. Every unidentified caller collapses into that single value, so a rate limit keyed on it throttles them as one client, and an allow list keyed on it either admits all of them or none.

When the address can be trusted

An IP address is only as trustworthy as the layer that determined it. Zuplo reports an address only where that layer establishes it, so the value is either trustworthy or undefined — never one the caller chose.

Deployment	Determined by	Trustworthy
Zuplo Cloud	The Zuplo edge	Yes
Zuplo Dedicated	Your environment, configured by Zuplo	Yes
Self-hosted	The proxy you run	Only if that proxy overwrites the header
Local development	Nothing — the caller is loopback	Reports 127.0.0.1

Zuplo Cloud and Zuplo Dedicated need no configuration. Self-hosted deployments depend on the proxy you run, covered in Self-hosted deployments.

The x-forwarded-for header

x-forwarded-for carries a client address through a chain of proxies. Each proxy appends the address it received the request from, producing a list:

Code
X-Forwarded-For: 203.0.113.7, 198.51.100.4

The header reaches your code and your backend unchanged, so you can read it directly:

Code
const chain = (request.headers.get("x-forwarded-for") ?? "")
  .split(",")
  .map((entry) => entry.trim())
  .filter(Boolean);

To use it correctly, understand what the list contains. A caller can send an X-Forwarded-For of its own, and every proxy after that appends to whatever arrived. So the front of the list is whatever the caller wrote, and only entries added by a hop you operate mean anything.

That leads to a few rules:

• Count positions from the end. The last entry was added by the hop nearest your gateway; the first came from the caller.
• Decide in advance how many hops you operate, and ignore anything beyond them. A caller can pad the front with as many entries as it likes.
• Don't search the list for an address you recognize — a caller can put one there.
• Expect IPv6 entries, which may be bracketed and carry a port, such as [2001:db8::1]:8080.

If you only need the caller's address, context.incomingRequestProperties.ip already gives it to you without any of this.

Running your own CDN or proxy in front of Zuplo

If your own CDN, load balancer, or WAF sits in front of your gateway, then that hop — not the end user — is the client Zuplo sees. incomingRequestProperties.ip returns its address.

To identify the end user, have your CDN write the address into a header of your own and read that header in your code:

Code
const endUserIp = request.headers.get("x-acme-client-ip");

This works only if your CDN overwrites that header on every request. If it merely adds the header when absent, a caller can supply their own value and it passes straight through to your code.

Zuplo Dedicated

Zuplo configures your Dedicated environment to determine the client address, so there's nothing for you to set up. context.incomingRequestProperties.ip returns the caller's address the same way it does on Zuplo Cloud.

Dedicated environments aren't identical to one another — they differ by cloud, region, and what sits in front of the gateway, such as a CDN or WAF you already operate. If you need to know exactly how the address is determined for your environment, or you're adding a network layer in front of it, contact your account team or support. Adding a hop in front of the gateway changes which address the gateway sees, as described in Running your own CDN or proxy in front of Zuplo.

Self-hosted deployments

On a self-hosted deployment you run the proxy in front of the gateway, so determining the client address is yours to configure. The gateway reads it from the x-real-ip request header.

Your proxy must overwrite that header rather than pass one through. If a client-supplied x-real-ip reaches the gateway untouched, any caller can choose its own address by sending it. NGINX's real_ip module does this correctly by default. Confirm the behavior against your own configuration before relying on the address for anything security-sensitive.

Geolocation

To act on where a caller is rather than their address, incomingRequestProperties already carries resolved geolocation — country, city, region, latitude, longitude, asn, and more. There's no need to geolocate the IP address yourself. See ZuploContext.