# Auth0 Fastify Api

> >

- **Type:** Skill
- **Install:** `agentstack add skill-auth0-agent-skills-auth0-fastify-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [auth0](https://agentstack.voostack.com/s/auth0)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [auth0](https://github.com/auth0)
- **Source:** https://github.com/auth0/agent-skills/tree/main/plugins/auth0/skills/auth0-fastify-api

## Install

```sh
agentstack add skill-auth0-agent-skills-auth0-fastify-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

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

### 2. Create Auth0 API

You need an **API** (not Application) in Auth0:

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

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

### 4. Configure Auth Plugin

Create your Fastify server (`server.js`):

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

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

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

Test protected endpoint (requires access token):

```bash
# 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 ` 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
- `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

- [Auth0 Fastify API Documentation](https://auth0.com/docs/quickstart/backend/fastify)
- [SDK GitHub Repository](https://github.com/auth0/auth0-fastify)
- [Access Tokens Guide](https://auth0.com/docs/secure/tokens/access-tokens)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [auth0](https://github.com/auth0)
- **Source:** [auth0/agent-skills](https://github.com/auth0/agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-auth0-agent-skills-auth0-fastify-api
- Seller: https://agentstack.voostack.com/s/auth0
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.