Allow custom headers for self-hosted instances

[jeankhawand]

Summary

Add support for configuring custom HTTP headers when connecting to self-hosted instances.

Problem

Some self-hosted deployments sit behind a reverse proxy, authentication gateway, API gateway, or zero-trust solution that requires additional HTTP headers on every request.

If the client only supports the instance URL and standard authentication, these deployments may be unreachable even though the underlying service is fully compatible.

Example use case

A company hosts an instance behind an access proxy such as Cloudflare Access, an API gateway, or another authentication layer.

Requests may require additional headers such as:

CF-Access-Client-Id: <client-id>
CF-Access-Client-Secret: <client-secret>

Or more generally:

X-API-Key: <key>
X-Custom-Auth: <token>

Without support for custom headers, users may need to:

• bypass or weaken their existing security setup
• create an additional proxy specifically for the client
• expose the instance differently
• or be unable to use the self-hosted integration

Proposed solution

Allow optional custom headers to be configured for self-hosted instances.

For example:

url: https://example.internal
headers:
  CF-Access-Client-Id: ${CF_ACCESS_CLIENT_ID}
  CF-Access-Client-Secret: ${CF_ACCESS_CLIENT_SECRET}

These headers should be included in requests made to the configured instance.

Ideally, sensitive header values should support environment variables or another secret-storage mechanism rather than requiring plaintext secrets in configuration.

Why this is important

Custom authentication and proxy headers are common in enterprise and security-conscious self-hosted environments.

Supporting custom headers would allow self-hosted instances to work with existing access-control infrastructure without requiring users to modify or weaken their network architecture.

It also keeps the feature generic rather than requiring provider-specific integrations for Cloudflare Access, API gateways, reverse proxies, or other authentication systems.