Proxying traffic to Coveo: High-level guidance

This is for:

Business Analyst System Administrator

This article describes a simple pattern for routing your application’s requests to Coveo through your own reverse proxy. It’s intentionally high-level. It’s not an implementation guide. Remember that Coveo won’t be able to troubleshoot your setup.

Architecture at a glance

Client → Your reverse proxy (on-premises or cloud) → Coveo endpoints over HTTPS

The reverse proxy can be any standard product (for example, nginx, Apache httpd, HAProxy, Envoy, cloud load balancer with proxying). Choose what your team is familiar with or something that you already operate.

High-level setup

  1. Deploy a reverse proxy. Host it where you prefer. Ensure that outbound HTTPS to the internet is allowed.

  2. Use your domain. Serve the proxy on a hostname you control and present a valid public TLS certificate.

  3. Define upstreams to Coveo. Point the proxy to your organization’s Coveo endpoints over HTTPS.

  4. Keep requests intact. Forward the method, path, query string, and headers without rewriting.

  5. Enforce upstream TLS validation. The proxy must verify Coveo’s certificates and hostnames.

Endpoints and routing

Coveo exposes distinct APIs. Plan separate logical routes (often separate virtual hosts) for:

  • Core organization endpoint (search and related APIs, for example, <YOUR_ORGANIZATION_ID>.org.coveo.com).

  • Analytics endpoint (Usage Analytics, for example, <YOUR_ORGANIZATION_ID>.analytics.org.coveo.com).

  • Optional admin endpoint (only if you choose to proxy admin traffic, for example, <YOUR_ORGANIZATION_ID>.admin.org.coveo.com).

Your proxy should send the correct Host header and SNI for each target endpoint. In practice, this means the upstream request should use the Coveo hostname for both HTTP Host and TLS SNI, not your proxy’s hostname.

Critical considerations

  • API key IP restrictions.

    If your Coveo API keys are allow-listed by IP, add the egress IPs of your reverse proxy (or NAT) to the allow list. If you run active/active across regions or zones, include every possible egress.

  • High availability (HA).

    Treat your proxy as a critical path, running at least two instances across failure domains.

  • Preserve the client IP.

    Do not mask the user’s IP:

    • Enforce an X-Forwarded-For header with the client IP as the left-most value.

    • This is required for correct application behavior, including Usage Analytics attribution.

  • Avoid rewriting.

    Rewriting paths, query parameters, headers, encodings, or bodies can trigger WAF rules or change behavior. Notable exceptions:

    • Set Host and TLS SNI to the Coveo upstream hostname.

    • Set the X-Forwarded-For header.

  • TLS everywhere.

    Use HTTPS from clients to your proxy and from your proxy to Coveo.

    • Validate upstream certificates and hostnames.

    • Prefer modern TLS and keep certificates current.

  • Split routes by endpoint.

    Maintain distinct routes for your core and analytics endpoints. Only add an admin route if you intend to proxy it. A single proxy can host multiple routes but splitting core and analytics features minimizes breakage if one endpoint is deny-listed by an ad blocker or a security tool.

  • WAF and security controls.

    If you enable a WAF in front of the proxy, tune rules to avoid false positives on valid API traffic. Don’t strip authentication headers.

  • Static egress.

    If your environment uses dynamic egress IPs, front the proxy with a NAT or gateway that provides a stable egress, as you may require allow-listing in your API key configurations.

  • No unintended caching.

    Don’t cache API POSTs or other non-idempotent requests. Respect response cache directives if you introduce any caching layer.

  • Resource limits.

    Ensure header size, body size, and concurrent connection limits in the proxy accommodate your workload. Don’t decompress or recompress content unless required.

Checklist

Before going live, verify that your reverse proxy configuration meets the following requirements:

  • ❏ Upstream TLS verification is enabled and passing.

  • ❏ Host and SNI are set to Coveo target hostnames.

  • ❏ X-Forwarded-For preserves the original client IP (left-most address is the client device).

  • ❏ There are no rewrites of path, query, headers, or body.

  • ❏ API keys work through the proxy and egress IPs are added to allow lists if they’re used.

  • ❏ Separate routes for core and analytics endpoints are configured.

  • ❏ Health checks, timeouts, retries, and connection pooling are configured.

  • ❏ HA configuration works via instance drain or failure simulation.

  • ❏ Monitoring dashboards and alerts are available.

  • ❏ Go live gradually. Start with a small percentage of traffic, then increase it while monitoring.

Next steps

Now that your reverse proxy infrastructure is ready, configure your UI framework to route requests through it:

  • Headless or Atomic: Configure the framework to use your proxy endpoints. See Configuring a proxy in the Headless documentation.

  • JSUI: Use the requestModifier function to redirect network calls to your proxy domain. See Modify network calls for implementation details.