JWT Issuer and Audience Checks

Set issuer and audience correctly so tokens from the wrong tenant or app are rejected at the edge. The gateway compares the `iss` and `aud` claims in the JWT

Set issuer and audience correctly so tokens from the wrong tenant or app are rejected at the edge. The gateway compares the iss and aud claims in the JWT payload against the values in your authorizer config. This page explains how each check works and what error messages indicate a mismatch.

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 sets issuer to "https://issuer.example.com" and audience to "api-audience". The gateway checks the iss and aud claims in every token presented to an auth: true route and returns a 401 if either does not match exactly.

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