npx skills add ...
npx skills add auth0/agent-skills --skill auth0-fastify-api
npx skills add auth0/agent-skills --skill auth0-fastify-api
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.
Protect Fastify API endpoints with JWT access token validation using @auth0/auth0-fastify-api.
auth0-quickstart skill first@auth0/auth0-fastify for session-based authauth0-react, auth0-vue, or auth0-angular for client-side authauth0-nextjs skillauth0-react-native for React Native/ExpoYou need an API (not Application) in Auth0:
Or create manually in Auth0 Dashboard → Applications → APIs
Create .env:
Create your Fastify server (server.js):
Test public endpoint:
Test protected endpoint (requires access token):
| 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 |
auth0-quickstart - Basic Auth0 setupauth0-fastify - For server-rendered Fastify web apps with sessionsauth0-mfa - Add Multi-Factor Authenticationauth0-cli - Manage Auth0 resources from the terminalPlugin Options:
domain - Auth0 tenant domain (required)audience - API identifier from Auth0 API settings (required)Request Properties:
request.user - Decoded JWT claims objectrequest.user.sub - User ID (subject)Middleware:
fastify.requireAuth() - Protect route with JWT validationfastify.requireAuth({ scopes: 'read:data' }) - Require specific scopefastify.requireAuth({ scopes: ['read:data', 'write:data'] }) - Require specific scopesCommon Use Cases:
preHandler: fastify.requireAuth() (see Step 5)request.user.subrequest.user['namespace/claim']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 });// 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
};
});curl http://localhost:3001/api/public# First, obtain an access token (e.g. via Auth0 Dashboard > APIs > Test tab)
curl http://localhost:3001/api/private \
-H "Authorization: Bearer $ACCESS_TOKEN"