JWT Issuer, Audience, and Why Tokens Still Fail

The short answer: A token can look valid and still fail because the gateway checks not just the signature but also the issuer and audience you configured for that route family.

When to read this

• JWT validation passes in one environment and fails in another.
• You need to explain auth config to non-specialists.
• You want fewer trial-and-error auth changes in production.

What matters in practice

• Signature validation alone is not enough.
• Issuer and audience mismatches are common after environment changes.
• Document the expected token contract next to the route docs.

Concrete example

        {
        "authorizer": {
          "type": "jwt",
          "secret": "$secret.JWT_SECRET",
          "algorithm": "HS256",
          "issuer": "https://issuer.example.com",
          "audience": "api-audience"
        },
        "paths": [
          { "method": "GET", "path": "/health", "response": { "status": "ok" } },
          {
            "method": "GET",
            "path": "/private/orders",
            "auth": true,
            "integration": { "type": "http_proxy", "server": "orders" }
          }
        ]
      }

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

• This repo does not add a GUI for validating sample tokens.
• If the identity provider is misconfigured, the gateway can only report the failure, not resolve the upstream cause.

FAQ

What is the most common mistake?

Using a token minted for one audience against a route configured for another.

Should I skip issuer checks in dev?

No. Relaxing core checks creates drift that surfaces later in production.

Related docs

• jwt hs256 setup
• jwt issuer and audience checks
• jwt common 401 errors

Last reviewed: March 6, 2026