Use JWT Claims to Personalize Upstream Requests

The short answer: If your upstream only needs a few identity fields, map verified claims into headers or query parameters at the gateway and keep the service contract simple.

When to read this

• Downstream services need sub, tenant, or plan values but should not parse tokens themselves.
• You want one place to decide which claims are forwarded.
• You need consistent identity propagation across multiple upstreams.

What matters in practice

• Only forward claims that the downstream actually uses.
• Keep mapping names stable so backend contracts stay readable.
• Use gateway variables when a route needs fixed metadata plus user-specific data.

Concrete example

        {
        "paths": [
          {
            "method": "GET",
            "path": "/proxy/{.+}",
            "auth": true,
            "integration": { "type": "http_proxy", "server": "upstream" },
            "mapping": {
              "headers": {
                "x-user-id": "$request.jwt.sub",
                "x-region": "$config.region"
              },
              "query": {
                "actor": "$request.jwt.sub"
              }
            },
            "variables": {
              "region": "eu-west-1"
            }
          }
        ]
      }

The example above is intentionally small because the best gateway configs stay readable. Add only the route, auth, and mapping behavior you actually need.

How this maps to the current gateway

The current codebase already supports the behavior discussed here through its config schema, route matcher, and integration handlers. That is why this project is a good fit for reader-first examples: the docs and blog can point to real, implemented behavior instead of hypothetical gateway features.

What this product does not do

• The mapper resolves simple placeholders; it is not a full policy engine or templating runtime.
• If a claim is missing, the mapped value becomes null and should be handled deliberately.

FAQ

Can I map query params and headers in the same route?

Yes. The current mapping implementation supports both.

Should I pass the whole token downstream?

Usually no. Forward only the fields the service actually needs.

Related docs

• mapping jwt claims
• mapping request headers
• mapping debugging null values

Last reviewed: March 6, 2026