auth0-fastify-api

★ 37

Use when securing Fastify API endpoints with JWT Bearer token validation, scope/permission checks, or stateless auth - integrates @auth0/auth0-fastify-api for…

🔥🔥🔥✓ VerifiedFreeQuick setup

#git

🧩 One of 7 skills in the auth0/agent-skills package — works on its own, and pairs well with its siblings.

Use when securing Fastify API endpoints with JWT Bearer token validation, scope/permission checks, or stateless auth - integrates @auth0/auth0-fastify-api for…

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.

name: auth0-fastify-api description: > Use when protecting Fastify API endpoints with JWT Bearer token validation or scope checks. Integrates @auth0/auth0-fastify-api for stateless APIs receiving access tokens from frontends or mobile apps. license: Apache-2.0 metadata: author: Auth0 support@auth0.com version: '1.0.0' openclaw: emoji: "\U0001F510" homepage: https://github.com/auth0/agent-skills requires: bins: - auth0

Auth0 Fastify API Integration

Protect Fastify API endpoints with JWT access token validation using @auth0/auth0-fastify-api.

When NOT to Use

Server-rendered web applications - Use @auth0/auth0-fastify for session-based auth
Single Page Applications - Use auth0-react, auth0-vue, or auth0-angular for client-side auth
Next.js applications - Use auth0-nextjs skill
Mobile applications - Use auth0-react-native for React Native/Expo

Related Skills

auth0-quickstart - Basic Auth0 setup
auth0-fastify - For server-rendered Fastify web apps with sessions
auth0-mfa - Add Multi-Factor Authentication
auth0-cli - Manage Auth0 resources from the terminal

Quick Reference

Plugin Options:

domain - Auth0 tenant domain (required)
audience - API identifier from Auth0 API settings (required)

Request Properties:

request.user - Decoded JWT claims object
request.user.sub - User ID (subject)

Middleware:

fastify.requireAuth() - Protect route with JWT validation
fastify.requireAuth({ scopes: 'read:data' }) - Require specific scope
fastify.requireAuth({ scopes: ['read:data', 'write:data'] }) - Require specific scopes

Common Use Cases:

Protect routes → Use preHandler: fastify.requireAuth() (see Step 5)
Get user ID → request.user.sub
Custom claims → Access via request.user['namespace/claim']

References

Copy & paste — that's it

npx skills add https://github.com/auth0/agent-skills --skill auth0-fastify-api

Run this in your project — your agent picks the skill up automatically.

Prerequisites

Fastify API application (v5.x or newer)
Node.js 20 LTS or newer
Auth0 API configured (not Application - must be API resource)
If you don't have Auth0 set up yet, use the auth0-quickstart skill first

Quick Start Workflow

1. Install SDK

Copy & paste — that's it

npm install @auth0/auth0-fastify-api fastify dotenv

2. Create Auth0 API

You need an API (not Application) in Auth0:

Copy & paste — that's it

# Using Auth0 CLI
auth0 apis create \
  --name "My Fastify API" \
  --identifier https://my-api.example.com

Or create manually in Auth0 Dashboard → Applications → APIs

3. Configure Environment

Create .env:

Copy & paste — that's it

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=https://my-api.example.com

4. Configure Auth Plugin

Create your Fastify server (server.js):

Copy & paste — that's it

import 'dotenv/config';
import Fastify from 'fastify';
import fastifyAuth0Api from '@auth0/auth0-fastify-api';

const fastify = Fastify({ logger: true });

// Register Auth0 API plugin
await fastify.register(fastifyAuth0Api, {
  domain: process.env.AUTH0_DOMAIN,
  audience: process.env.AUTH0_AUDIENCE,
});

fastify.listen({ port: 3001 });

5. Protect Routes

Copy & paste — that's it

// Public route - no authentication
fastify.get('/api/public', async (request, reply) => {
  return {
    message: 'Hello from a public endpoint!',
    timestamp: new Date().toISOString(),
  };
});

// Protected route - requires valid JWT
fastify.get('/api/private', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  return {
    message: 'Hello from a protected endpoint!',
    user: request.user.sub,
    timestamp: new Date().toISOString(),
  };
});

// Protected route with user info
fastify.get('/api/profile', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  return {
    profile: request.user,  // JWT claims
  };
});

6. Test API

Test public endpoint:

Copy & paste — that's it

curl http://localhost:3001/api/public

Test protected endpoint (requires access token):

Copy & paste — that's it

# First, obtain an access token (e.g. via Auth0 Dashboard > APIs > Test tab)
curl http://localhost:3001/api/private \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Common Mistakes

Mistake	Fix
Created Application instead of API in Auth0	Must create API resource in Auth0 Dashboard → Applications → APIs
Missing Authorization header	Include `Authorization: Bearer <token>` in all protected endpoint requests
Wrong audience in token	Client must request token with matching `audience` parameter
Using ID token instead of access token	Must use access token for API auth, not ID token
Not handling 401/403 errors	Implement proper error handling for unauthorized/forbidden responses