express-oauth2-jwt-bearer

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

bash

gh api repos/auth0/node-oauth2-jwt-bearer/releases/latest --jq '.tag_name'

Use the returned version in all

package.json

dependency lines instead of any hardcoded version below.

• Node.js 18+ (20+ recommended; required for bootstrap script automation)
• Express 4.x or 5.x
• npm or yarn
• An Auth0 account with a configured API (Resource Server)
• Auth0 CLI (for automatic setup):

  npm install -g @auth0/auth0-cli

Agent instruction: Follow these steps to integrate

express-oauth2-jwt-bearer

into the user's Node.js API project.

1. Fetch latest version (see instruction above).
2. Install the SDK:
   bash

   npm install express-oauth2-jwt-bearer

3. Configure Auth0 — follow

   references/setup.md

   . If the user already provided their Auth0 Domain and API Audience in the prompt, use them directly — skip the bootstrap script and do NOT call

   AskUserQuestion

   to re-confirm. Otherwise, offer automatic setup via bootstrap script or manual setup.
4. Set up middleware — add to

   app.js

   or

   server.js

   :
   javascript

   import { auth } from 'express-oauth2-jwt-bearer';
   
   const checkJwt = auth({
     issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
     audience: process.env.AUTH0_AUDIENCE,
   });
   
   app.use(checkJwt); // apply globally, or per-route

5. Protect endpoints — apply middleware globally or to specific routes:
   javascript

   // Global protection
   app.use(checkJwt);
   
   // Or per-route
   app.get('/api/private', checkJwt, (req, res) => {
     res.json({ sub: req.auth.payload.sub });
   });

6. Add RBAC (optional) — use

   requiredScopes()

   or

   claimIncludes()

   for permission-based access:
   javascript

   import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer';
   
   app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
     res.json({ messages: [] });
   });

   Important:

   requiredScopes

   accepts a single argument — a space-separated string or an array. Do NOT pass multiple string arguments:

   requiredScopes('read:msg', 'write:msg')

   silently ignores everything after the first. Use

   requiredScopes('read:msg write:msg')

   or

   requiredScopes(['read:msg', 'write:msg'])

   instead.

7. Verify the integration — build and test:
   bash

   node server.js
   curl http://localhost:3000/api/private         # should return 401
   curl -H "Authorization: Bearer <token>" http://localhost:3000/api/private  # should return 200

8. Failcheck: If the server fails to start or tokens are rejected unexpectedly, check

   references/api.md

   for common issues. After 5-6 failed iterations, use

   AskUserQuestion

   to ask the user for more details about their environment.

• Setup Guide — Auth0 API registration, .env configuration, bootstrap script for automated setup, and secret management
• Integration Patterns — Protected endpoints, RBAC with scopes and claims, DPoP, CORS setup, error handling, and testing with curl
• API Reference & Testing — Full configuration options, claims reference, complete code example, testing checklist, and common issues

• auth0-express — For Express web apps with login UI (sessions, cookies)
• auth0-nextjs — For Next.js server-side web apps
• auth0-aspnetcore-api — BACKEND_API reference implementation for .NET
• go-jwt-middleware — JWT middleware for Go APIs
• auth0-api-python — JWT validation for Python APIs (Flask/FastAPI)
• auth0-cli — Manage Auth0 resources from the terminal

• express-oauth2-jwt-bearer on npm
• GitHub: auth0/node-oauth2-jwt-bearer
• Auth0 Node.js API Quickstart
• Auth0 APIs Dashboard
• RFC 6750 — Bearer Token Usage