How to Move Auth Out of Downstream Services

The short answer: Move auth to the gateway when downstream services mostly need verified identity context, not raw token validation logic.

When to read this

• Every microservice repeats the same bearer-token checks.
• Teams want fewer auth libraries and fewer per-service configuration errors.
• You need a consistent edge trust boundary.

What matters in practice

• Centralize verification first, then standardize the headers or params you forward.
• Do not remove downstream authorization decisions just because identity moved upstream.
• Document the trust contract for service owners.

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 gateway verifies tokens but does not implement a full authorization policy system.
• Services still need business-level authorization and data-level checks.

FAQ

Can I still inspect claims inside the service?

Yes, by forwarding specific values through headers or query parameters.

What is the biggest migration risk?

Forgetting to align downstream services on the new trusted identity contract.

Related docs

• auth route design public vs private
• mapping jwt claims
• public routes private routes and least privilege

Last reviewed: March 6, 2026