Protect Your Fastify API

This guide demonstrates how to protect Fastify API endpoints using JWT access tokens with the Auth0 Fastify API SDK.

Use AI to integrate Auth0

If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 API authentication automatically in minutes using agent skills.

Install:

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-fastify-api

Then ask your AI assistant:

Add Auth0 JWT authentication to my Fastify API

Your AI assistant will automatically create your Auth0 API, fetch credentials, install @auth0/auth0-fastify-api, configure the plugin, and protect your API endpoints with JWT validation. Full agent skills documentation →

Prerequisites: Before you begin, ensure you have the following installed:

• Node.js 20 LTS or newer
• npm 10+ or yarn 1.22+ or pnpm 8+

Verify installation: node --version && npm --version

Fastify Version Compatibility: This quickstart works with Fastify 5.x and newer.

Get Started

This quickstart demonstrates how to protect Fastify API endpoints using JWT access tokens. You’ll build a secure API that validates Auth0 access tokens and grants access to protected resources.

1. Create a new project

   Create a new directory for your Fastify API and initialize a Node.js project.

   mkdir auth0-fastify-api && cd auth0-fastify-api
   

   Initialize the project

   npm init -y
   

   Create the project structure

   touch server.js .env
   
2. Install the Auth0 Fastify API SDK

   Install the required dependencies

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

   Update your package.json to add start scripts:

   package.json

   {
     "name": "auth0-fastify-api",
     "version": "1.0.0",
     "type": "module",
     "main": "server.js",
     "scripts": {
       "start": "node server.js",
       "dev": "node --watch server.js"
     },
     "dependencies": {
       "@auth0/auth0-fastify-api": "^1.2.0",
       "dotenv": "^16.3.1",
       "fastify": "^5.0.0"
     }
   }
   
3. Setup your Auth0 API

   Next, you need to create a new API on your Auth0 tenant and add the environment variables to your project.

   You have two options to set up your Auth0 API: use a CLI command or configure manually via the Dashboard:

   CLI

   Run the following command in your project’s root directory to create an Auth0 API:

   Mac

   # Install Auth0 CLI (if not already installed)
   brew tap auth0/auth0-cli && brew install auth0
   
   # Create Auth0 API
   auth0 apis create \
     --name "My Fastify API" \
     --identifier https://my-fastify-api.example.com
   

   # Install Auth0 CLI (if not already installed)
   scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
   scoop install auth0
   
   # Create Auth0 API
   auth0 apis create `
     --name "My Fastify API" `
     --identifier https://my-fastify-api.example.com
   

   After creation, copy the Identifier and your Domain values, then create your .env file:

   .env

   AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
   AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
   

   This command will:

   1. Check if you’re authenticated (and prompt for login if needed)
   2. Create an Auth0 API with the specified identifier
   3. Display the API details including the domain and identifier

   Dashboard

   1. Go to the Auth0 Dashboard
   2. Navigate to Applications → APIs → Create API
   3. Enter a name for your API (e.g., “My Fastify API”)
   4. Set the Identifier (e.g., https://my-fastify-api.example.com)
      • This is your API audience and must be a valid URL format
      • It doesn’t need to be a real URL - it’s just an identifier
   5. Keep Signing Algorithm as RS256
   6. Click Create
   7. Copy the Identifier value from the Settings tab

   Create your .env file with the following values:

   .env

   AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
   AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
   

   Replace YOUR_AUTH0_DOMAIN with your Auth0 tenant domain (e.g., dev-abc123.us.auth0.com) and YOUR_API_IDENTIFIER with your API identifier from the dashboard (e.g., https://my-fastify-api.example.com).

   Verify your .env file exists: cat .env (Mac/Linux) or type .env (Windows)

4. Configure the Auth0 API plugin

   Create your Fastify server and register the Auth0 API plugin:

   server.js

   import 'dotenv/config';
   import Fastify from 'fastify';
   import fastifyAuth0Api from '@auth0/auth0-fastify-api';
   
   const fastify = Fastify({ logger: true });
   const port = process.env.PORT || 3001;
   
   // Register Auth0 API plugin
   await fastify.register(fastifyAuth0Api, {
     domain: process.env.AUTH0_DOMAIN,
     audience: process.env.AUTH0_AUDIENCE,
   });
   
   // Start server
   fastify.listen({ port }, (err) => {
     if (err) {
       fastify.log.error(err);
       process.exit(1);
     }
     fastify.log.info(`API server running at http://localhost:${port}`);
   });
   

   What this does:

   • Registers the Auth0 API plugin with your Auth0 domain and API audience
   • Configures JWT validation for incoming requests
   • Makes the requireAuth() preHandler available for protecting routes
5. Create API routes

   Add public and protected routes to your server.js:

   server.js

   import 'dotenv/config';
   import Fastify from 'fastify';
   import fastifyAuth0Api from '@auth0/auth0-fastify-api';
   
   const fastify = Fastify({ logger: true });
   const port = process.env.PORT || 3001;
   
   // Register Auth0 API plugin
   await fastify.register(fastifyAuth0Api, {
     domain: process.env.AUTH0_DOMAIN,
     audience: process.env.AUTH0_AUDIENCE,
   });
   
   // Public route - no authentication required
   fastify.get('/api/public', async (request, reply) => {
     return {
       message: 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
       timestamp: new Date().toISOString(),
     };
   });
   
   // Protected route - requires valid access token
   fastify.get('/api/private', {
     preHandler: fastify.requireAuth()
   }, async (request, reply) => {
     return {
       message: 'Hello from a protected endpoint! You successfully authenticated.',
       user: request.user.sub,
       timestamp: new Date().toISOString(),
     };
   });
   
   // Protected route - returns user information from token
   fastify.get('/api/profile', {
     preHandler: fastify.requireAuth()
   }, async (request, reply) => {
     return {
       message: 'Your user profile from the access token',
       profile: request.user,
     };
   });
   
   // Start server
   fastify.listen({ port }, (err) => {
     if (err) {
       fastify.log.error(err);
       process.exit(1);
     }
     fastify.log.info(`API server running at http://localhost:${port}`);
   });
   

   Key points:

   • Public routes don’t require authentication
   • Protected routes use preHandler: fastify.requireAuth() to require a valid JWT
   • request.user contains the decoded JWT claims for authenticated requests
   • The sub claim contains the user’s unique identifier
6. Run your API

   Start the development server:

   npm run dev
   

   Your API is now running at http://localhost:3001.

   The --watch flag in Node.js 20+ automatically restarts the server when files change.

7. Test your API

   Test the public endpoint (no authentication required):

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

   You should see:

   {
     "message": "Hello from a public endpoint! You don't need to be authenticated to see this.",
     "timestamp": "2024-01-15T10:30:00.000Z"
   }
   

   Test the protected endpoint without a token (should fail):

   curl http://localhost:3001/api/private
   

   You should see a 401 Unauthorized error:

   {
     "error": "Unauthorized",
     "message": "No authorization token was found"
   }
   

   To test with a valid token, you need to:

   1. Create a client application (web or mobile app) that authenticates users
   2. Configure the client to request an access token for your API (using the audience parameter)
   3. Use that access token in the Authorization header

   Example with a token:

   curl http://localhost:3001/api/private \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
   

Checkpoint

You should now have a protected API. Your API:

1. Accepts requests to public endpoints without authentication
2. Rejects requests to protected endpoints without a valid token
3. Validates JWT tokens against your Auth0 domain and audience
4. Provides user information from the token claims via request.user

---

Advanced Usage

Custom Token Claims with TypeScript

Extend the Token interface to add type safety for custom claims in your access tokens:

server.ts

import '@auth0/auth0-fastify-api';

// Extend the Token interface with your custom claims
declare module '@auth0/auth0-fastify-api' {
  interface Token {
    sub: string;
    permissions?: string[];
    'https://myapp.com/roles'?: string[];
    email?: string;
    email_verified?: boolean;
  }
}

Now TypeScript will recognize your custom claims:

server.ts

fastify.get('/api/profile', {
  preHandler: fastify.requireAuth()
}, async (request, reply) => {
  // TypeScript knows about these properties
  const userRoles = request.user['https://myapp.com/roles']; // string[] | undefined
  const permissions = request.user.permissions; // string[] | undefined
  const email = request.user.email; // string | undefined

  return {
    userId: request.user.sub,
    roles: userRoles || [],
    permissions: permissions || [],
    email: email,
  };
});

Custom claims must use namespaced URLs (e.g., https://myapp.com/roles) unless they’re standard OIDC claims. Learn more about custom claims.

Permission-Based Authorization

Check for specific permissions in the access token:

server.js

// Middleware to check for specific permission
function requirePermission(permission) {
  return async (request, reply) => {
    const permissions = request.user.permissions || [];

    if (!permissions.includes(permission)) {
      return reply.status(403).send({
        error: 'Forbidden',
        message: `Missing required permission: ${permission}`
      });
    }
  };
}

// Route requiring 'read:messages' permission
fastify.get('/api/messages', {
  preHandler: [
    fastify.requireAuth(),
    requirePermission('read:messages')
  ]
}, async (request, reply) => {
  return {
    messages: ['Message 1', 'Message 2', 'Message 3']
  };
});

// Route requiring 'write:messages' permission
fastify.post('/api/messages', {
  preHandler: [
    fastify.requireAuth(),
    requirePermission('write:messages')
  ]
}, async (request, reply) => {
  return {
    message: 'Message created successfully',
    id: 'msg_123'
  };
});

Permissions must be configured in your Auth0 API settings and granted to clients. Learn more about API permissions.

Role-Based Authorization

Implement role-based access control using custom claims:

server.js

// Middleware to check for specific role
function requireRole(role) {
  return async (request, reply) => {
    const roles = request.user['https://myapp.com/roles'] || [];

    if (!roles.includes(role)) {
      return reply.status(403).send({
        error: 'Forbidden',
        message: `Missing required role: ${role}`
      });
    }
  };
}

// Admin-only route
fastify.get('/api/admin/users', {
  preHandler: [
    fastify.requireAuth(),
    requireRole('admin')
  ]
}, async (request, reply) => {
  return {
    users: [
      { id: 1, name: 'User 1' },
      { id: 2, name: 'User 2' }
    ]
  };
});

// Manager or admin route
function requireAnyRole(...roles) {
  return async (request, reply) => {
    const userRoles = request.user['https://myapp.com/roles'] || [];
    const hasRole = roles.some(role => userRoles.includes(role));

    if (!hasRole) {
      return reply.status(403).send({
        error: 'Forbidden',
        message: `Missing required role. Need one of: ${roles.join(', ')}`
      });
    }
  };
}

fastify.get('/api/reports', {
  preHandler: [
    fastify.requireAuth(),
    requireAnyRole('admin', 'manager')
  ]
}, async (request, reply) => {
  return { reports: [] };
});

Roles must be added to tokens using Auth0 Actions. Learn how to add roles to tokens.

CORS Configuration

Enable CORS to allow requests from web applications:

npm install @fastify/cors

server.js

import cors from '@fastify/cors';

await fastify.register(cors, {
  origin: ['http://localhost:3000', 'http://localhost:5173'], // Your web app URLs
  credentials: true,
});

For production, specify exact origins:

server.js

await fastify.register(cors, {
  origin: [
    'https://myapp.com',
    'https://www.myapp.com'
  ],
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
});

Error Handling

Add comprehensive error handling for authentication errors:

server.js

// Custom error handler
fastify.setErrorHandler((error, request, reply) => {
  fastify.log.error(error);

  // Handle JWT validation errors
  if (error.statusCode === 401) {
    return reply.status(401).send({
      error: 'Unauthorized',
      message: error.message || 'Invalid or missing access token',
      code: 'UNAUTHORIZED'
    });
  }

  // Handle permission/role errors
  if (error.statusCode === 403) {
    return reply.status(403).send({
      error: 'Forbidden',
      message: error.message || 'Insufficient permissions',
      code: 'FORBIDDEN'
    });
  }

  // Handle other errors
  return reply.status(error.statusCode || 500).send({
    error: 'Internal Server Error',
    message: 'An unexpected error occurred',
    code: 'INTERNAL_ERROR'
  });
});

// Not found handler
fastify.setNotFoundHandler((request, reply) => {
  return reply.status(404).send({
    error: 'Not Found',
    message: `Route ${request.method} ${request.url} not found`,
    code: 'NOT_FOUND'
  });
});

Rate Limiting

Protect your API from abuse with rate limiting:

npm install @fastify/rate-limit

server.js

import rateLimit from '@fastify/rate-limit';

await fastify.register(rateLimit, {
  max: 100, // Maximum requests
  timeWindow: '1 minute', // Time window
  errorResponseBuilder: (request, context) => {
    return {
      error: 'Too Many Requests',
      message: `Rate limit exceeded. Try again in ${context.after}`,
      retryAfter: context.after
    };
  }
});

// Apply stricter limits to specific routes
fastify.get('/api/expensive-operation', {
  preHandler: fastify.requireAuth(),
  config: {
    rateLimit: {
      max: 10,
      timeWindow: '1 minute'
    }
  }
}, async (request, reply) => {
  return { result: 'expensive operation result' };
});

---

Troubleshooting

Common Issues and Solutions

”No authorization token was found”

Problem: The API cannot find the access token in the request.

Solutions:

1. Ensure the Authorization header is present: Authorization: Bearer YOUR_TOKEN
2. Check that “Bearer” is included before the token
3. Verify the token is not expired

”Invalid token” or “jwt malformed”

Problem: The token format is invalid.

Solutions:

1. Ensure you’re using an access token, not an ID token
2. The token should be obtained with your API’s audience parameter
3. Check that the token is a valid JWT (should have three parts separated by dots)

“Invalid signature”

Problem: The token signature doesn’t match.

Solutions:

1. Verify AUTH0_DOMAIN matches the domain that issued the token
2. Ensure you’re using RS256 signing algorithm (default)
3. Check that the token hasn’t been modified

”Invalid audience”

Problem: The token’s audience doesn’t match your API.

Solution: The client application must request a token with the correct audience:

// In your client app
const token = await getAccessTokenSilently({
  authorizationParams: {
    audience: 'https://my-fastify-api.example.com' // Must match your API identifier
  }
});

CORS errors in browser

Problem: Browser blocks API requests due to CORS policy.

Solution: Install and configure @fastify/cors:

npm install @fastify/cors

import cors from '@fastify/cors';

await fastify.register(cors, {
  origin: 'http://localhost:3000', // Your frontend URL
  credentials: true
});

---

Next Steps

Now that you have a protected API, consider exploring:

• Fastify Web App Quickstart - Build a web application that calls your API
• Role-Based Access Control - Implement fine-grained permissions
• API Authorization Best Practices - Learn about access token best practices
• Monitor Your API - Set up logging and monitoring

---

Resources

• auth0-fastify-api GitHub - Source code and examples
• Fastify Documentation - Learn more about Fastify
• Auth0 API Authentication - Understanding access tokens
• Auth0 Community - Get help from the community