Designing Public vs Private Routes

Separate public and private paths clearly so your API contract stays understandable for clients and maintainers. Group public routes (health, docs, login)

Separate public and private paths clearly so your API contract stays understandable for clients and maintainers. Group public routes (health, docs, login) together and private routes (user data, admin) together in your config for readability. This page offers patterns for organizing routes by access level.

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 places a private route with auth: true alongside the authorizer config. In a real config, you would add public routes (without auth: true) for endpoints like /health or /login so clients can access them without a 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