Security Limitations and Non-Goals

Understand what the gateway does not implement today so you can avoid overclaiming its security surface. The gateway handles JWT validation, issuer/audience

Understand what the gateway does not implement today so you can avoid overclaiming its security surface. The gateway handles JWT validation, issuer/audience checks, and token extraction. It does not implement role-based access control, token revocation lists, scope-based permissions, or request signing. Plan your security architecture accordingly.

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 shows the full extent of the gateway's auth capability: a shared secret, algorithm, issuer, audience, and per-route auth flag. Features beyond this -- such as RBAC, scopes, or token blacklists -- must be implemented in your upstream service or via a pre-process hook.

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