JWT And Security

Use HS256 JWT auth when you control the signing secret and want simple issuer and audience validation. This guide walks through configuring the authorizer block

Use HS256 JWT auth when you control the signing secret and want simple issuer and audience validation. This guide walks through configuring the authorizer block with a shared secret, setting the algorithm, and enabling auth on specific routes. HS256 is the simplest JWT setup and works well for internal APIs and single-tenant applications.

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 the authorizer with type: "jwt", an HS256 algorithm, and a secret loaded from $env.JWT_SECRET. The issuer and audience fields add claim validation, and the /private path has auth: true to require a valid token.

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