JWT: Common 401 Errors

Debug missing bearer tokens, expired tokens, and invalid claims before blaming the upstream service. The gateway returns specific 401 error messages for each

Debug missing bearer tokens, expired tokens, and invalid claims before blaming the upstream service. The gateway returns specific 401 error messages for each validation failure, including "missing authorization header", "token expired", "invalid issuer", and "invalid audience". This page catalogs each error and its fix.

Last reviewed: 2026-03-06

When to use this

Use the JWT and security guides when you need to protect routes with token-based authentication. The gateway validates JWT tokens at the edge before the request reaches your upstream, reducing load on your backend and centralizing auth checks in one place.

Key concepts

• The gateway supports HS256 JWT validation with a shared secret. The secret is configured in the authorizer block and should be stored as a Cloudflare secret, not hardcoded in config.

• Issuer (iss) and audience (aud) claims are validated when configured. If either check fails, the gateway returns a 401 with a specific error message identifying which claim was invalid.

• Auth is opt-in per route: only paths with auth: true require a valid JWT. All other paths are public by default, even when an authorizer is configured.

• The gateway extracts the token from the Authorization: Bearer <token> header. No other token locations (cookies, query params) are supported.

• The gateway does not implement role-based access control, token revocation, or scope-based permissions. These must be handled by your upstream service or a pre-process hook.

Repo-grounded example

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

This snippet configures JWT validation with issuer and audience checks. When a request fails validation, the gateway returns a 401 JSON response with an error message identifying the specific failure (expired token, wrong issuer, wrong audience, or missing header).

Troubleshooting

• If you get a 401 "missing authorization header" error, confirm the client sends the Authorization header with the Bearer prefix (note the space after Bearer).

• If you get a 401 "token expired" error, check the exp claim in your JWT -- the gateway compares it against the current UTC time on the Cloudflare edge node.

• If issuer or audience validation fails, decode your token at jwt.io and compare the iss and aud claims exactly (case-sensitive) against the values in your authorizer config.

• If a public route unexpectedly returns 401, verify that the route does not have auth: true set -- check for typos like "auth": "true" (string vs boolean).

Related docs

• authorizer

• authentication

• gateway troubleshooting matrix