Preflight Checklist

• I could not find a solution in the existing issues, docs, nor discussions
• I have joined the ZITADEL chat

Describe the docs your are missing or that are wrong

Zitadel allows overwriting the requested host using headers. This was mostly implemented for login v2, but may solve other use cases as well.

I found just another simple reference on the subject: https://zitadel.com/docs/self-hosting/manage/custom-domain#running-zitadel-behind-a-reverse-proxy which links to some examples. However, there is no definitive resource on the headers we accept and how they influence zitadel's behaviour. I think we should create a dedicated page with all headers and what they do, and expand further in certain solution and example guides.

Additional Context

Example use-case

We recently got a customer with the following use case:

They have 4 relevant components, I've renamed / simplified some terms to more generic ones.

1. Application: completing Oauth authentication to obtain a token.
2. API: called by the application, authenticated by the token.
3. Reverse proxy: sits between Zitadel and the public internet
4. Zitadel: on a private network

The application obtains a token over the public network, through the reverse proxy, from zitadel. Using the public domain of the reversed proxy. That domain becomes the issuer of the token. The token is then used in a call to the API. However, the API is also on the private network, so it calls Zitadel (introspection?) using the internal network, using the internal Hostname. Zitadel now refuses the token because the issuer does not match the host.

I'm not sure, but I think this also came up on discord a number of times where APIs are part of the same Docker network as Zitadel.

Header definitions

All headers used by the zitadel API are currently defined as constants here: