How to Debug 401s in Worker-Based APIs

The short answer: Most worker-side 401s come from missing bearer tokens, wrong issuer or audience values, expired tokens, or a mismatch between the selected authorizer and the route.

When to read this

• Protected routes return 401 before the upstream sees traffic.
• You are switching between JWT, Auth0, and Supabase modes.
• You need a fast debugging sequence for incident response.

What matters in practice

• Confirm the route requires auth before debugging the identity provider.
• Check the authorizer type, issuer, audience, and secret or JWKS source together.
• Use deterministic error codes to separate token format issues from upstream identity failures.

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

• The gateway can tell you why local validation failed, but it cannot fix broken IdP configuration for you.
• Some upstream identity errors still require checking Auth0 or Supabase dashboards and logs.

FAQ

What is the fastest first check?

Verify the Authorization: Bearer ... header is present and the route is actually marked auth: true.

Can clock skew cause failures?

Yes. Expired and not-yet-active tokens can both surface as auth failures.

Related docs

• jwt common 401 errors
• auth0 error handling
• supabase required env vars

Last reviewed: March 6, 2026