NGINX API gateway routing by header

Yes — NGINX can route requests based on a header, and this is a common API gateway pattern.

Simple example

If you want to route based on a custom header like X-Api-Version:

http {
    upstream v1_backend {
        server 10.0.0.11:8080;
    }

    upstream v2_backend {
        server 10.0.0.12:8080;
    }

    map $http_x_api_version $backend_upstream {
        default     v1_backend;
        "v2"        v2_backend;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://$backend_upstream;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
    }
}

How it works

• NGINX reads the incoming header X-Api-Version
• map assigns an upstream name based on that header
• proxy_pass sends the request to the selected backend

Important notes

• Use the $http_... variable format for headers:
  • X-Api-Version → $http_x_api_version
  • X-Tenant-Id → $http_x_tenant_id
• Header names are lowercased and dashes become underscores in variable form
• map is usually better than if for this use case

Routing by multiple headers

You can also combine headers:

map "$http_x_api_version:$http_x_tenant_id" $backend_upstream {
    default         v1_backend;
    "v2:tenant1"    v2_backend;
}

If you want header-based routing plus path-based routing

You can combine both using separate location blocks and map.

If you want, I can give you:

1. a full NGINX API gateway config,
2. routing by JWT claim/header,
3. routing by tenant header,
4. or an NGINX Plus / open-source comparison.