Quickstart: JWT-Protected Route

Protect a single route with HS256 JWT validation without forcing authentication on every endpoint. This guide shows how to add an authorizer block and flag

Protect a single route with HS256 JWT validation without forcing authentication on every endpoint. This guide shows how to add an authorizer block and flag individual paths with auth: true. Use this when you control the JWT signing secret and need per-route protection.

Last reviewed: 2026-03-06

When to use this

Use these quickstart guides when you are setting up Serverless API Gateway for the first time or adding a new integration pattern. Each guide walks through one isolated concern so you can deploy incrementally instead of configuring everything at once.

Key concepts

• Every quickstart produces a deployable wrangler.toml and JSON config pair -- you can run wrangler deploy at the end of each guide.

• Guides are ordered from simplest (health endpoint) to most complex (Auth0/Supabase passwordless), so earlier guides serve as prerequisites for later ones.

• Config can come from a local file, Cloudflare KV, or the SAG_API_CONFIG_JSON environment variable -- choose based on your deploy workflow.

• All guides use the same JSON config schema, so patterns you learn in one guide transfer directly to others.

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 block with HS256 signing, an issuer check, and an audience check. The auth: true flag on the /private path tells the gateway to require a valid bearer token for that route only.

Troubleshooting

• If wrangler deploy fails with a config error, validate your JSON against the schema file (api-config.schema.json) before investigating further.

• If the health endpoint returns 404, confirm that your wrangler.toml points to the correct main entrypoint and that the config file is being loaded.

• If JWT or Auth0 routes return 500, check that all required environment variables and secrets are set in your Cloudflare dashboard or .dev.vars file.

• Use wrangler tail to stream live logs from the deployed worker and see the exact error message the gateway produces.

Related docs

• introduction

• overview

• gateway troubleshooting matrix