Auth0 Fastify Api

Auth0 Fastify API Integration

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

Prerequisites

When NOT to Use

Quick Start Workflow

1. Install SDK

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

2. Create Auth0 API

You need an API (not Application) in Auth0:

# 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:

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

4. Configure Auth Plugin

Create your Fastify server (server.js):

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

// 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:

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

Test protected endpoint (requires access token):

curl http://localhost:3001/api/private \
  -H "Authorization: Bearer YOUR_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 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 |

Related Skills

Quick Reference

Plugin Options:

Request Properties:

Middleware:

Common Use Cases:

References