> For the complete documentation index, see [llms.txt](https://docs.serverlessapigateway.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.serverlessapigateway.com/security/jwt-hs256-setup/jwt-protect-only-selected-routes.md).

# JWT: Protect Only Selected Routes

Gate only sensitive endpoints by setting `auth: true` where it matters instead of forcing auth on the whole API. The authorizer block configures how tokens are validated, but routes are public by default. This page explains how to mix public and protected routes in the same gateway config.

**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

```json
{
  "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 an authorizer block alongside a single `auth: true` route. Any other paths in the `paths` array without `auth: true` remain publicly accessible, even though the authorizer is configured globally.

## 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](/configuration/authorizer.md)
* [authentication](/configuration/authentication.md)
* [gateway troubleshooting matrix](/troubleshooting/wrangler-deploy-guide/gateway-troubleshooting-matrix.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.serverlessapigateway.com/security/jwt-hs256-setup/jwt-protect-only-selected-routes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.