Labsco
auth0 logo

express-oauth2-jwt-bearer

★ 37

by auth0 · part of auth0/agent-skills

Use when adding Auth0 token validation to Express or Node.js APIs - integrates express-oauth2-jwt-bearer SDK to protect Node.js API endpoints with JWT Bearer…

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#git#security
🧩 One of 7 skills in the auth0/agent-skills package — works on its own, and pairs well with its siblings.

Use when adding Auth0 token validation to Express or Node.js APIs - integrates express-oauth2-jwt-bearer SDK to protect Node.js API endpoints with JWT Bearer…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by auth0

Use when adding Auth0 token validation to Express or Node.js APIs - integrates express-oauth2-jwt-bearer SDK to protect Node.js API endpoints with JWT Bearer… npx skills add https://github.com/auth0/agent-skills --skill express-oauth2-jwt-bearer Download ZIPGitHub37

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:

Copy & paste — that's it
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.

When NOT to Use

Use Case Recommended Skill Building a server-side web app with login UI (Express sessions) auth0-express Building a Next.js app with server-side auth auth0-nextjs Building a React/Angular/Vue SPA auth0-react, auth0-angular, auth0-vue Building a React Native or mobile app auth0-react-native, auth0-android, auth0-swift ASP.NET Core Web API auth0-aspnetcore-api Go API with JWT middleware go-jwt-middleware Python API (Flask/FastAPI) auth0-api-python Node.js API using the older express-jwt package express-jwt

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

Related Skills

Quick Reference

Core Middleware

Function Description Returns auth(options?) JWT Bearer validation middleware Handler — 401 if token invalid/missing requiredScopes(scopes) Validates token has all required scopes Handler — 403 if scopes missing scopeIncludesAny(scopes) Validates token has at least one scope Handler — 403 if no match claimEquals(claim, value) Validates a claim equals a value Handler — 401 if mismatch claimIncludes(claim, ...values) Validates claim includes all values Handler — 401 if incomplete claimCheck(fn, desc?) Custom claim validation function Handler — 401 if fn returns false

Configuration Options

Option Type Description issuerBaseURL string Full issuer URL with https://. Optional — defaults to the ISSUER_BASE_URL env var audience string API Identifier from Auth0 Dashboard. Optional — defaults to the AUDIENCE env var tokenSigningAlg string Signing algorithm (default: RS256; use HS256 for symmetric) authRequired boolean Set false to make authentication optional (default: true) clockTolerance number Clock skew tolerance in seconds (no default; undefined unless set) dpop DPoPOptions DPoP configuration (see integration.md)

Environment Variables

Variable Description ISSUER_BASE_URL Full issuer URL with https://, e.g. https://your-tenant.us.auth0.com (auto-detected by SDK) AUDIENCE API Identifier, e.g. https://your-api-identifier (auto-detected by SDK)

Request Object

After successful validation, req.auth contains:

Copy & paste — that's it
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:

Package Purpose express-oauth2-jwt-bearer Main package. Express middleware for JWT Bearer validation. Published to npm. access-token-jwt Low-level JWT verification utilities (used internally). oauth2-bearer RFC 6750 Bearer token extraction (used internally).

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

Auth Flow Comparison

Auth Pattern SDK When to Use JWT Bearer (stateless) express-oauth2-jwt-bearer APIs called by SPAs, mobile apps, M2M clients Session-based (stateful) @auth0/express-openid-connect Web apps with login UI and server-side sessions

Testing Quick Reference

Copy & paste — that's it
# 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 " http://localhost:3000/api/private

# 3. Verify 403 with valid token but missing scope
curl -H "Authorization: Bearer " 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