Using Self-hosted & Reverse Proxies with Vercel | Vercel Knowledge Base

Verified Proxy

Verified Proxy allows the Vercel CDN to work with external reverse proxies placed in front of your deployments.

IMPORTANT: We strongly advise against using reverse proxies in front of your Vercel deployment. Implementing a reverse proxy can reduce Vercel’s ability to effectively protect your application from malicious traffic. Additionally, routing requests through multiple network hops may introduce extra latency and negatively impact performance.

Before proceeding, review our guidance on reverse proxies: https://vercel.com/guides/can-i-use-a-proxy-on-top-of-my-vercel-deployment

If you do use a proxy in front of your deployment, be aware that the Vercel platform will always display a "Proxy Detected" banner in the Firewall page. This is to help you and your team recognise when traffic is being routed through an external proxy, which is not recommended and can impact your site's performance and reduce our ability to protect your site.

Why Use Verified Proxy?

Vercel protects your application from L3, L4, and L7 DDoS attacks on all plans by default. The Vercel Firewall leverages hundreds of signals to analyze request patterns, automatically identifying and challenging or blocking malicious traffic.

However, if you use reverse proxies in front of your Vercel deployment, there is a risk that our DDoS mitigation systems may flag the proxy’s IP addresses during periods of high traffic. To prevent legitimate traffic from being inadvertently blocked, you can set up Verified Proxy. This feature ensures that Vercel trusts a specific set of proxy headers when they are passed from known provider egress IP ranges, allowing traffic from your reverse proxy to be accurately identified and processed.

Considerations and Potential Drawbacks

• Security & visibility loss: When behind proxies, Vercel’s ability to maintain full visibility into incoming traffic is reduced. This can impact the effectiveness of the Vercel Firewall, limiting its ability to automatically challenge or block malicious requests such as those associated with DDoS attacks. Additionally, using a self-hosted reverse proxy introduces another potential point of failure outside of Vercel’s control. Any proxy-related downtime may require manual intervention from your team to resolve.
• Performance impact: Implementing a proxy adds additional network hops, which can negatively impact your application performance. If your proxy solution is not globally distributed, it may introduce additional latency for users in different regions. Additionally, using a proxy bypasses Vercel’s automatic mitigation strategies for global infrastructure issues, affecting your application's reliability and resiliency.
• Incorrect geolocation reporting: Routing traffic through a proxy causes all requests to reach Vercel from the proxy’s public IP address, rather than the original client’s location. As a result, geolocation data may be inaccurate and reflect the proxy’s location instead of the end user’s. Enterprise customers can leverage Verified Proxy Advanced to override this behavior and ensure accurate geolocation reporting.
• Dual caching: When using an external proxy alongside the Vercel CDN, both layers may cache responses. It is important to ensure that these caches remain synchronized to prevent serving stale or outdated content to your users.

How to Set Up Verified Proxy

Prerequisite

1. TLS certificate issuance/renewal: When using the same hostname end-to-end across the request life cycle (Client -> Proxy -> Vercel), Vercel must be able to access http://<YOUR_DOMAIN>/.well-known/acme-challenge/* URL paths on port 80 (plain HTTP). To ensure successful domain validation, please disable automatic HTTP to HTTPS redirection for these URLs and exclude them from your external proxy's WAF or bot protection settings. This will prevent HTTP-01 challenge requests from being blocked or denied.
2. Cache invalidation: Vercel purges its edge cache on every deployment. Your proxy must purge its cache at the same time, and must never cache https://<YOUR_DOMAIN>/.well-known/vercel/* URL paths.
3. Plan eligibility
   • Hobby / Pro: Verified Proxy Lite only (supported CDN providers below).
   • Enterprise: Verified Proxy Lite and Verified Proxy Advanced (self-hosted proxies, geolocation preservation).

Automatic vs. Manual Enablement

Verified Proxy is automatically enabled for the providers listed below on all plans. Any other provider or a self-hosted proxy (for example, Nginx, HAProxy, etc) requires a manual onboarding process (Enterprise only).

Supported Providers

Self-Hosted Reverse Proxies

Setting up Verified Proxy with self-hosted reverse proxies is only available on Enterprise plans

If you are running self-hosted reverse proxies, please ensure the following requirements are met:

1. Your proxy must have static egress IP addresses assigned. We cannot support dynamic IP addresses.
2. Your proxy must send a custom request header that carries the real client IP (e.g., x-${team-slug}-connecting-ip).
3. Your proxy must enable SNI (Server Name Indication) on outbound TLS connections.
4. Use consistent and predictable Vercel project domains for onboarding. For example, use *.vercel.example.com and ensure your Proxy always sends traffic to those specific hostnames.

For detailed setup instructions, please contact your Customer Success Manager (CSM) or Account Executive.

Troubleshooting Verified Proxy Configurations

The most common issue is a missing or incorrect SNI (Server Name Indication) hostname in your proxy. Verify that SNI is enabled and the correct hostname is passed.

Provider-specific tips:

• Akamai: Review Forward Host Header settings, and enable Use SNI TLS Extension option (docs).
• Fastly: Set SNI hostname and Certificate hostname in your Origin settings (docs). This must be the same as your Vercel project domain.
• Self-hosted: Review your proxy provider’s documentation for guidance.

How can I verify that my Verified Proxy configuration is working?

Create a test API route that logs all the incoming headers and confirm that the required header (e.g., CF-Connecting-IP) is passed via your Proxy correctly:

import { NextRequest, NextResponse } from "next/server"

export const dynamic = 'force-dynamic'

export async function GET(req: NextRequest) {
  return NextResponse.json({ headers: Object.fromEntries(req.headers.entries()) });
}

Can I restrict direct access to my Vercel apps?

Verified Proxy does not block direct access. To restrict it, use Vercel WAF or Trusted IPs.

Why don’t I see the visitor’s IP/geolocation in my app?

That is expected because our system sees your Proxy IP as a client IP address. If you need to see the real client IP/geolocation throughout your application, you must enable Verified Proxy Advanced (Enterprise only).

Verified Proxy Advanced is a paid add-on available exclusively on Enterprise plans. For pricing and additional details, please contact your Customer Success Manager or Account Executive.

Does Verified Proxy affect the Monitoring UI?

Yes. By default, the Monitoring UI displays the proxy’s IP address as the client IP. Enabling Verified Proxy Advanced allows the Monitoring UI to show the original client IP instead.