auth-agent: lightweight JWT authentication example

[Muhammad-Bin-Ali]

examples/auth-agent — protect agent connections with JWTs

Example showing how to authenticate WebSocket and HTTP connections to a Cloudflare Agent using JWTs.

What it demonstrates

• onBeforeConnect — verify a JWT query param before upgrading to WebSocket
• onBeforeRequest — verify a JWT (Bearer header or query param) before handling HTTP requests
• A demo /api/token endpoint that issues JWTs with jose (HMAC-SHA256, iss/aud claims)
• Passing user identity from JWT claims into the AI chat system prompt

Key patterns

routeAgentRequest(request, env, {
  onBeforeConnect: async (req) => {
    const token = new URL(req.url).searchParams.get("token");
    const payload = await verifyToken(env, token);
    if (!payload) return Response.json({ error: "Unauthorized" }, { status: 401 });
    return req;
  },
  onBeforeRequest: async (req) => {
    const authHeader = req.headers.get("Authorization");
    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7)
      : new URL(req.url).searchParams.get("token");
    const payload = await verifyToken(env, token);
    if (!payload) return Response.json({ error: "Unauthorized" }, { status: 401 });
    return req;
  }
});

The token endpoint is demo scaffolding — in production, replace it with your own auth service. The onBeforeConnect / onBeforeRequest middleware stays the same.

Files

File	Purpose
src/server.ts	Worker entry — token endpoint, JWT verify, chat agent
src/auth-client.ts	Client-side token fetch and storage
src/client.tsx	React UI — name form + chat
README.md	Docs with copy-paste patterns

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6900f49

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/agents@948

npm i https://pkg.pr.new/@cloudflare/ai-chat@948

npm i https://pkg.pr.new/@cloudflare/codemode@948

npm i https://pkg.pr.new/hono-agents@948

commit: 93723d5

[threepointone]

this felt too heavy for an example, so I rewrote it to be jwt only and more as a guide. thanks for the pr!