Node OAuth2 JWT Bearer Integration#

The express-oauth2-jwt-bearer package provides Express middleware for validating Auth0 JWT Bearer access tokens. It handles token extraction, signature verification, audience and issuer validation, and expiry checks per RFC 6750 — letting you focus on business logic rather than JWT parsing.

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.

Prerequisites#

• 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

When NOT to Use#

Use CaseRecommended SkillBuilding a server-side web app with login UI (Express sessions)auth0-expressBuilding a Next.js app with server-side authauth0-nextjsBuilding a React/Angular/Vue SPAauth0-react, auth0-angular, auth0-vueBuilding a React Native or mobile appauth0-react-native, auth0-android, auth0-swiftASP.NET Core Web APIauth0-aspnetcore-apiGo API with JWT middlewarego-jwt-middlewarePython API (Flask/FastAPI)auth0-api-pythonNode.js API using the older express-jwt packageexpress-jwt

Quick Start Workflow#

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.

Detailed Documentation#

• 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

Common Mistakes#

MistakeSymptomFixCreated an Application instead of an API in Auth0 DashboardToken validation fails; wrong audienceCreate a new API (Resource Server) in Auth0 Dashboard → APIsAudience doesn't match API identifier exactly401 Unauthorized — "Audience mismatch"Copy the exact API Identifier string from Auth0 Dashboard → APIsDomain includes https:// prefixError: Invalid URL at startupUse hostname only: your-tenant.us.auth0.com, not https://...Checking scope claim instead of permissions for RBAC403 always returned or permissions ignoredUse requiredScopes() for scope-based RBAC; use claimIncludes('permissions', 'read:data') for Auth0 RBAC permission claimsCORS not configured before auth middlewarePreflight OPTIONS requests return 401Add cors() middleware before auth() in the middleware chain.env file not loadedundefined for domain/audienceAdd import 'dotenv/config' at the top of the entry filereq.auth is undefinedTypeError: Cannot read properties of undefinedVerify checkJwt middleware runs before the handler

Related Skills#

• 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

Quick Reference#

Core Middleware#

FunctionDescriptionReturnsauth(options?)JWT Bearer validation middlewareHandler — 401 if token invalid/missingrequiredScopes(scopes)Validates token has all required scopesHandler — 403 if scopes missingscopeIncludesAny(scopes)Validates token has at least one scopeHandler — 403 if no matchclaimEquals(claim, value)Validates a claim equals a valueHandler — 401 if mismatchclaimIncludes(claim, ...values)Validates claim includes all valuesHandler — 401 if incompleteclaimCheck(fn, desc?)Custom claim validation functionHandler — 401 if fn returns false

Configuration Options#

OptionTypeDescriptionissuerBaseURL``stringAuth0 domain with https:// (required unless using env vars)audience``stringAPI Identifier from Auth0 Dashboard (required unless using env vars)tokenSigningAlg``stringSigning algorithm (default: RS256; use HS256 for symmetric)authRequired``booleanSet false to make authentication optional (default: true)clockTolerance``numberClock skew tolerance in seconds (no default; undefined unless set)dpop``DPoPOptionsDPoP configuration (see integration.md)

Environment Variables#

VariableDescriptionISSUER_BASE_URLAuth0 domain with https:// (auto-detected by SDK)AUDIENCEAPI Identifier (auto-detected by SDK)

Request Object#

After successful validation, req.auth contains:

typescript

req.auth.payload    // Decoded JWT payload (sub, iss, aud, exp, permissions, etc.)
req.auth.header     // JWT header (alg, typ, kid)
req.auth.token      // Raw JWT string

SDK Architecture#

The node-oauth2-jwt-bearer monorepo contains three packages:

PackagePurposeexpress-oauth2-jwt-bearerMain package. Express middleware for JWT Bearer validation. Published to npm.access-token-jwtLow-level JWT verification utilities (used internally).oauth2-bearerRFC 6750 Bearer token extraction (used internally).

In practice, you only install and import express-oauth2-jwt-bearer.

Auth Flow Comparison#

Auth PatternSDKWhen to UseJWT Bearer (stateless)express-oauth2-jwt-bearerAPIs called by SPAs, mobile apps, M2M clientsSession-based (stateful)@auth0/express-openid-connectWeb apps with login UI and server-side sessions

Testing Quick Reference#

bash

# Get test token from Auth0 Dashboard → APIs → your API → Test tab
# Copy the token, then:

# 1. Verify 401 on protected route (no token)
curl -v http://localhost:3000/api/private

# 2. Verify 200 with valid token
curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/private

# 3. Verify 403 with valid token but missing scope
curl -H "Authorization: Bearer <paste-token-here>" http://localhost:3000/api/admin

# 4. Verify CORS preflight
curl -v -X OPTIONS http://localhost:3000/api/private \
  -H "Origin: http://localhost:5173" \
  -H "Access-Control-Request-Method: GET" \
  -H "Access-Control-Request-Headers: Authorization"

References#

• 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