Auth0 Fastify API

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

Security Scan

The skill's purpose and instructions align with an Auth0 + Fastify integration, but the runtime instructions reference environment variables and tooling (Auth0 CLI, npm installs) that are not declared in the skill metadata — this mismatch is concerning and should be resolved before trusting the skill.

Purpose & Capability

Name, description, and SKILL.md consistently describe integrating @auth0/auth0-fastify-api to protect Fastify endpoints with JWTs. The steps, examples, and references match the stated purpose.

Instruction Scope

The SKILL.md instructs creating and reading a .env (AUTH0_DOMAIN, AUTH0_AUDIENCE) and running commands (npm install, optional auth0 CLI usage). The skill metadata declared no required environment variables or binaries — the runtime instructions therefore implicitly require access to environment variables and developer tooling that the metadata doesn't advertise.

Install Mechanism

There is no install spec (instruction-only), which is low risk. However, the instructions explicitly require running npm install and optionally the Auth0 CLI; these will fetch and execute code from third-party sources at runtime. This is expected for an integration skill but worth noting because the skill itself doesn't enumerate or manage those installs.

Credentials

The skill asks the developer to populate AUTH0_DOMAIN and AUTH0_AUDIENCE in .env and the code samples read process.env.*. Yet requires.env is empty. Additionally, creating an Auth0 API via the auth0 CLI implies use of Auth0 management credentials (not declared). The skill requests or uses environment/config values without declaring them, which is disproportionate to the declared metadata.

Persistence & Privilege

always is false and there is no install step that modifies other skills or system-wide agent settings. The skill does not request persistent platform privileges in its metadata.

What to consider before installing

This skill appears to be a straightforward Auth0 + Fastify integration, but metadata and runtime instructions don't fully match. Before installing or using it: 1) Treat AUTH0_DOMAIN and AUTH0_AUDIENCE as required configuration — the skill should declare them; avoid pasting sensitive management credentials into .env unless you understand where they will be stored. 2) If you plan to run the example auth0 CLI command, recognize that requires Auth0 management credentials (not declared by the skill). 3) Install dependencies (npm install @auth0/auth0-fastify-api fastify dotenv) yourself in a controlled/dev environment and inspect package sources and versions. 4) Confirm the skill will not read other environment variables or files you consider sensitive. 5) Prefer obtaining the skill from an official, versioned repository (the SKILL.md points to Auth0's repos) and verify that the package names are official. If the publisher cannot clarify the undeclared env vars and CLI credential requirements, treat the mismatch as a red flag and proceed cautiously.

Auth0 Fastify API Integration

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

---

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

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

---

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

---

Related Skills

• auth0-quickstart - Basic Auth0 setup
• auth0-fastify - For server-rendered Fastify web apps with sessions
• auth0-mfa - Add Multi-Factor Authentication

---

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

• Auth0 Fastify API Documentation
• SDK GitHub Repository
• Access Tokens Guide