express-oauth2-jwt-bearer
Use when protecting Express or Node.js API endpoints with JWT Bearer token validation, scope-based access control, or DPoP binding. Integrates express-oauth2-jwt-bearer — use even if the user says "validate tokens in my Express API" or "protect my Node.js API endpoints".
- Installs
- 469
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/auth0/agent-skills --skill express-oauth2-jwt-bearer- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads express-oauth2-jwt-bearer automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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:
gh api repos/auth0/node-oauth2-jwt-bearer/releases/latest --jq '.tag_name'Use the returned version in all
package.jsondependency 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 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 |
Quick Start Workflow
Agent instruction: Follow these steps to integrate
express-oauth2-jwt-bearerinto the user's Node.js API project.
Fetch latest version (see instruction above).
Install the SDK:
npm install express-oauth2-jwt-bearerConfigure Auth0 — follow
references/setup.md. If the user already provided their Auth0 Domain and API Audience in the prompt, write them to a.envfile asISSUER_BASE_URL(the full issuer URL, includinghttps://) andAUDIENCE— the SDK reads these automatically. Skip the bootstrap script and do NOT callAskUserQuestionto re-confirm. Never hardcode the domain or audience as literal strings (or||fallback defaults) inserver.js/app.js— they belong in.envonly. Otherwise, offer automatic setup via bootstrap script or manual setup.Set up middleware — first create a
.envfile with the Auth0 values, then load it and add the middleware.express-oauth2-jwt-bearerreadsISSUER_BASE_URLandAUDIENCEfrom the environment automatically, soauth()needs no arguments:# .env ISSUER_BASE_URL=https://your-tenant.us.auth0.com AUDIENCE=https://your-api-identifierimport 'dotenv/config'; // load .env before the SDK reads process.env import { auth } from 'express-oauth2-jwt-bearer'; // Reads ISSUER_BASE_URL and AUDIENCE from the environment — no config needed const checkJwt = auth(); app.use(checkJwt); // apply globally, or per-routeKeep the issuer and audience in
.env— do not inline literal values or pass them as arguments here.Protect endpoints — apply middleware globally or to specific routes:
// Global protection app.use(checkJwt); // Or per-route app.get('/api/private', checkJwt, (req, res) => { res.json({ sub: req.auth.payload.sub }); });Add RBAC (optional) — use
requiredScopes()orclaimIncludes()for permission-based access:import { auth, requiredScopes, claimIncludes } from 'express-oauth2-jwt-bearer'; app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => { res.json({ messages: [] }); });Important:
requiredScopesaccepts 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. UserequiredScopes('read:msg write:msg')orrequiredScopes(['read:msg', 'write:msg'])instead.Verify the integration — build and test:
node server.js curl http://localhost:3000/api/private # should return 401 curl -H "Authorization: Bearer <token>" http://localhost:3000/api/private # should return 200Failcheck: If the server fails to start or tokens are rejected unexpectedly, check
references/api.mdfor common issues. After 5-6 failed iterations, useAskUserQuestionto 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
| Mistake | Symptom | Fix |
|---|---|---|
| Created an Application instead of an API in Auth0 Dashboard | Token validation fails; wrong audience | Create a new API (Resource Server) in Auth0 Dashboard → APIs |
| Audience doesn't match API identifier exactly | 401 Unauthorized — "Audience mismatch" | Copy the exact API Identifier string from Auth0 Dashboard → APIs |
ISSUER_BASE_URL missing the https:// scheme | Error: Invalid URL at startup | ISSUER_BASE_URL must be the full issuer URL: https://your-tenant.us.auth0.com |
Checking scope claim instead of permissions for RBAC | 403 always returned or permissions ignored | Use requiredScopes() for scope-based RBAC; use claimIncludes('permissions', 'read:data') for Auth0 RBAC permission claims |
| CORS not configured before auth middleware | Preflight OPTIONS requests return 401 | Add cors() middleware before auth() in the middleware chain |
.env file not loaded | undefined for domain/audience | Add import 'dotenv/config' at the top of the entry file |
Hardcoded domain/audience in source (incl. process.env.X || 'literal' fallbacks) | Secrets committed to source; fails security review | Put values in .env (ISSUER_BASE_URL / AUDIENCE) and let auth() read them automatically — no literal fallbacks |
req.auth is undefined | TypeError: Cannot read properties of undefined | Verify 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
| 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:
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
# 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
FAQ
What does the express-oauth2-jwt-bearer skill do?
Use when protecting Express or Node.js API endpoints with JWT Bearer token validation, scope-based access control, or DPoP binding. Integrates express-oauth2-jwt-bearer — use even if the user says "validate tokens in my Express API" or "protect my Node.js API endpoints".
How do I install express-oauth2-jwt-bearer?
Run npx skills add https://github.com/auth0/agent-skills --skill express-oauth2-jwt-bearer in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/express-oauth2-jwt-bearer/ (personal) or .claude/skills/express-oauth2-jwt-bearer/ (project).
Which AI agents can use express-oauth2-jwt-bearer?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is express-oauth2-jwt-bearer safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains express-oauth2-jwt-bearer?
It is published by auth0 in auth0/agent-skills, and it is an official skill from the maker of the technology it covers. It has 469 recorded installs.
More from auth0/agent-skills
auth0
auth0/agent-skills
Use when adding, fixing, or improving how an app authenticates users or protects an API, or when using or configuring any Auth0 feature — signing users in and out, sessions and tokens, guarding routes and endpoints, MFA, passwordless passkey login (WebAuthn), SSO, Organizations, RBAC, custom domains, Universal Portals for hosted account and organization self-service, or Universal Login branding. Also use to audit a tenant's health, security, and plan fit (CheckMate), to debug why an auth flow fails, to migrate from another auth provider, or to set up the Vercel native integration. Covers any web, mobile, or backend framework and every Auth0 SDK, tool, and API. Use even if the user never mentions Auth0.
auth0-quickstart
auth0/agent-skills
Use when adding Auth0 authentication to any app and unsure which SDK or skill to use. Detects the project's framework and routes to the right setup workflow — use this as the entry point even if the user just says "add login to my app" or "set up Auth0" without naming a framework.
auth0-nextjs
auth0/agent-skills
Use when adding Auth0 login, logout, protected pages, or middleware to a Next.js application. Supports App Router and Pages Router with @auth0/nextjs-auth0 — use even if the user says "add login to my Next.js app" or "protect my Next.js routes".
auth0-react
auth0/agent-skills
Use when adding Auth0 login, logout, protected routes, or user sessions to a React SPA. Integrates @auth0/auth0-react — use even if the user says "add login to my React app" or "protect my React routes" without naming the SDK.
auth0-react-native
auth0/agent-skills
Use when adding Auth0 login, logout, or biometric auth to a bare React Native app (not Expo). Integrates react-native-auth0 with native deep linking.
auth0-express
auth0/agent-skills
Use when adding session-based login, logout, or protected routes to an Express.js web application. Integrates express-openid-connect — use even if the user says "add login to my Express app" or "protect my Express routes".
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.