> ## Documentation Index
> Fetch the complete documentation index at: https://auth0-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Login to Your Fastify Application

> This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Fastify web application using the Auth0 Fastify SDK.

export const HowToSchema = () => <script type="application/ld+json">
    {'{"@context":"https://schema.org","@type":"HowTo"}'}
  </script>;

export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => {
  const [displayText, setDisplayText] = useState(children);
  const [copyText, setCopyText] = useState(children);
  const wrapperRef = React.useRef(null);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      if (!window.autorun || !window.rootStore) {
        return;
      }
      unsubscribe = window.autorun(() => {
        let processedChildrenForDisplay = children;
        let processedChildrenForCopy = children;
        for (const [key, value] of window.rootStore.variableStore.values.entries()) {
          const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
          let displayValue = value;
          if (key === "{yourClientSecret}" && value !== "{yourClientSecret}") {
            displayValue = value.substring(0, 3) + "*****MASKED*****";
          }
          processedChildrenForDisplay = processedChildrenForDisplay.replaceAll(new RegExp(escapedKey, "g"), displayValue);
          processedChildrenForCopy = processedChildrenForCopy.replaceAll(new RegExp(escapedKey, "g"), value);
        }
        setDisplayText(processedChildrenForDisplay);
        setCopyText(processedChildrenForCopy);
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  useEffect(() => {
    if (!wrapperRef.current) return;
    const originalWriteText = navigator.clipboard.writeText.bind(navigator.clipboard);
    let isOverriding = false;
    const handleClick = e => {
      const button = e.target.closest('[data-testid="copy-code-button"]');
      if (!button || !wrapperRef.current.contains(button)) return;
      isOverriding = true;
      navigator.clipboard.writeText = text => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
          return originalWriteText(copyText);
        }
        return originalWriteText(text);
      };
      setTimeout(() => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
        }
      }, 100);
    };
    const wrapper = wrapperRef.current;
    wrapper.addEventListener('click', handleClick, true);
    return () => {
      wrapper.removeEventListener('click', handleClick, true);
      if (navigator.clipboard.writeText !== originalWriteText) {
        navigator.clipboard.writeText = originalWriteText;
      }
    };
  }, [copyText]);
  return <div ref={wrapperRef}>
      <CodeBlock filename={filename} icon={icon} language={language} lines highlight={highlight}>
        {displayText}
      </CodeBlock>
    </div>;
};

export const CreateInteractiveApp = ({placeholderText = 'Auth0', appType = 'regular_web', allowedCallbackUrls = ['localhost:3000'], allowedLogoutUrls = ['localhost:3000'], allowedOriginUrls = ['localhost:3000']}) => {
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  const [storeReady, setStoreReady] = useState(false);
  const [displayForm, setDisplayForm] = useState(true);
  useEffect(() => {
    const init = () => setStoreReady(true);
    if (window.rootStore) {
      window.rootStore.clientStore.setSelectedClient(null);
      window.rootStore.clientStore.setSelectedClientSecret(undefined);
      init();
    } else {
      window.addEventListener('adu:storeReady', init);
    }
    return () => {
      window.removeEventListener('adu:storeReady', init);
    };
  }, []);
  useEffect(() => {
    if (!storeReady) return;
    const disposer = autorun(() => {
      const rootStore = window.rootStore;
      setIsAuthenticated(rootStore.sessionStore.isAuthenticated);
    });
    return () => {
      disposer();
    };
  }, [storeReady]);
  if (!storeReady || typeof window === 'undefined' || !displayForm) {
    return <></>;
  }
  const login = () => {
    const baseUrl = window.rootStore.config.apiBaseUrl;
    const returnTo = encodeURIComponent(window.location.href);
    window.location.href = `${baseUrl}/auth/user/login?returnTo=${returnTo}`;
  };
  const Card = ({className = '', children}) => {
    return <div className={`
          flex border rounded-2xl
          border-gray-950/10 dark:border-white/10
          py-3.5 px-4 gap-2
          text-sm text-gray-900 dark:text-gray-200
          ${className}
        `}>
        {children}
      </div>;
  };
  const Button = ({children, ...props}) => {
    return <button className="bg-[--button-primary] text-[--foreground-inverse] px-[1.125rem] py-1.5 rounded-lg font-medium" {...props}>
        {children}
      </button>;
  };
  const CreateApplicationForm = () => {
    const [name, setName] = useState('');
    const [isLoading, setIsLoading] = useState(false);
    const [error, setError] = useState('');
    const handleSubmit = async () => {
      if (!name.trim()) {
        setError('Application name is required');
        return;
      }
      setIsLoading(true);
      setError(null);
      try {
        await window.rootStore.clientStore.createClient({
          name: name.trim(),
          app_type: appType,
          callbacks: allowedCallbackUrls,
          allowed_logout_urls: allowedLogoutUrls,
          web_origins: allowedOriginUrls,
          client_metadata: {
            created_by: 'quickstart-docs-app-creation-component'
          }
        });
        setDisplayForm(false);
      } catch (err) {
        console.error('Error creating client:', err);
        const errorMessage = err instanceof Error ? err.message : 'Failed to create application';
        setError(errorMessage);
      } finally {
        setIsLoading(false);
      }
    };
    return <Card className="flex-col items-start p-4 gap-3.75">
        <span className="font-medium text-gray-900 dark:text-gray-200">
          Create Auth0 App
        </span>
        <div className="w-full flex gap-2">
          <input id="app-name" name={name} className="
              w-full max-w-[448px] h-11 py-2 px-4 
              border rounded-lg border-gray-950/10 dark:border-white/10 
              text-gray-900 dark:text-gray-200
              focus:outline-none dark:focus:outline-none
            " placeholder={`My ${placeholderText} App`} value={name} onChange={e => setName(e.target.value)} />
          <Button onClick={handleSubmit}>
            {isLoading ? 'Creating...' : 'Create'}
          </Button>
        </div>
        {error && <p className="text-red-500">{error}</p>}
      </Card>;
  };
  const SignInForm = () => {
    return <Card className="items-center">
        <Button onClick={login}>Log in</Button> <span>to create the app</span>
      </Card>;
  };
  return isAuthenticated ? <CreateApplicationForm /> : <SignInForm />;
};

<HowToSchema />

export function generateRandomString(length) {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  return Array.from({
    length
  }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
}

export const localEnvSnippet = `AUTH0_DOMAIN={yourDomain}
AUTH0_CLIENT_ID={yourClientId}
AUTH0_CLIENT_SECRET={yourClientSecret}
SESSION_SECRET=${generateRandomString(64)}
APP_BASE_URL=http://localhost:3000`;

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai" iconType="solid" defaultOpen>
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-fastify
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my Fastify app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `@auth0/auth0-fastify`, configure the plugin, and create all necessary routes and views. [Full agent skills documentation →](/docs/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

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

  **Fastify Version Compatibility:** This quickstart works with **Fastify 5.x** and newer.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Fastify application. You'll build a secure web app with login, logout, and user profile features using the Auth0 Fastify SDK.

<Steps>
  <Step title="Create a new project" stepNumber={1}>
    Create a new directory for your Fastify application and initialize a Node.js project.

    ```shellscript theme={null}
    mkdir auth0-fastify && cd auth0-fastify
    ```

    Initialize the project

    ```shellscript theme={null}
    npm init -y
    ```

    Create the project structure

    ```shellscript theme={null}
    touch server.js .env
    ```
  </Step>

  <Step title="Install the Auth0 Fastify SDK" stepNumber={2}>
    Install the required dependencies

    ```shellscript theme={null}
    npm install @auth0/auth0-fastify fastify dotenv @fastify/view ejs
    ```

    <Info>
      We're using `@fastify/view` with `ejs` for server-side rendering. You can use any template engine supported by Fastify.
    </Info>

    Update your `package.json` to add start scripts:

    ```json package.json theme={null}
    {
      "name": "auth0-fastify",
      "version": "1.0.0",
      "type": "module",
      "main": "server.js",
      "scripts": {
        "start": "node server.js",
        "dev": "node --watch server.js"
      },
      "dependencies": {
        "@auth0/auth0-fastify": "^1.2.0",
        "@fastify/view": "^10.0.0",
        "dotenv": "^16.3.1",
        "ejs": "^3.1.9",
        "fastify": "^5.0.0"
      }
    }
    ```
  </Step>

  <Step title="Setup your Auth0 App" stepNumber={3}>
    Next, you need to create a new application on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp placeholderText="Fastify" appType="regular_web" allowedCallbackUrls={["http://localhost:3000/auth/callback"]} allowedLogoutUrls={["http://localhost:3000"]} />

        <AuthCodeBlock children={localEnvSnippet} language="shellscript" filename=".env" />
      </Tab>

      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --app --type regular --framework fastify --name "My Fastify App" --port 3000
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --app --type regular --framework fastify --name "My Fastify App" --port 3000
          ```
        </CodeGroup>

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 Regular Web Application configured for `http://localhost:3000`
          3. Generate a `.env` file with `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `SESSION_SECRET`, and `APP_BASE_URL`
        </Note>
      </Tab>

      <Tab title="Dashboard">
        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Navigate to **Applications** → **Create Application**
        3. Enter a name for your application (e.g., "My Fastify App")
        4. Select **Regular Web Applications** and click **Create**
        5. In the **Settings** tab, configure the following:

        | Setting               | Value                                 |
        | --------------------- | ------------------------------------- |
        | Allowed Callback URLs | `http://localhost:3000/auth/callback` |
        | Allowed Logout URLs   | `http://localhost:3000`               |

        6. Scroll down and click **Save Changes**
        7. Copy the **Domain**, **Client ID**, and **Client Secret** values from the **Basic Information** section

        Create your `.env` file with the following values:

        ```bash .env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
        AUTH0_CLIENT_ID=YOUR_CLIENT_ID
        AUTH0_CLIENT_SECRET=YOUR_CLIENT_SECRET
        SESSION_SECRET=use-a-long-random-string-at-least-64-characters
        APP_BASE_URL=http://localhost:3000
        ```

        <Warning>
          Replace `YOUR_AUTH0_DOMAIN` with your Auth0 tenant domain (e.g., `dev-abc123.us.auth0.com`), `YOUR_CLIENT_ID` with your application's Client ID, and `YOUR_CLIENT_SECRET` with your application's Client Secret from the dashboard.
        </Warning>

        Generate a secure secret for session encryption:

        ```bash theme={null}
        openssl rand -hex 64
        ```

        Copy the output and use it as the `SESSION_SECRET` value in your `.env` file.
      </Tab>
    </Tabs>

    <Tip>
      Verify your `.env` file exists: `cat .env` (Mac/Linux) or `type .env` (Windows)
    </Tip>
  </Step>

  <Step title="Configure the Auth0 plugin" stepNumber={4}>
    Create your Fastify server and register the Auth0 plugin:

    ```javascript server.js {1-4,7-8,11-18,21-22} lines theme={null}
    import 'dotenv/config';
    import Fastify from 'fastify';
    import fastifyView from '@fastify/view';
    import fastifyAuth0 from '@auth0/auth0-fastify';
    import ejs from 'ejs';

    const fastify = Fastify({ logger: true });
    const port = process.env.PORT || 3000;

    // Register view engine
    await fastify.register(fastifyView, {
      engine: { ejs },
      root: './views',
    });

    // Register Auth0 plugin
    await fastify.register(fastifyAuth0, {
      domain: process.env.AUTH0_DOMAIN,
      clientId: process.env.AUTH0_CLIENT_ID,
      clientSecret: process.env.AUTH0_CLIENT_SECRET,
      appBaseUrl: process.env.APP_BASE_URL,
      sessionSecret: process.env.SESSION_SECRET,
    });

    // Start server
    fastify.listen({ port }, (err) => {
      if (err) {
        fastify.log.error(err);
        process.exit(1);
      }
      fastify.log.info(`Server running at http://localhost:${port}`);
    });
    ```

    **What this does:**

    * Registers the view engine for rendering HTML templates
    * Configures the Auth0 plugin with your credentials
    * Automatically creates routes at `/auth/login`, `/auth/logout`, and `/auth/callback`
    * Handles session management with encrypted cookies
  </Step>

  <Step title="Create view templates" stepNumber={5}>
    Create a `views` directory and add template files:

    ```shellscript Mac/Linux theme={null}
    mkdir views && touch views/home.ejs views/profile.ejs
    ```

    ```powershell Windows theme={null}
    New-Item -ItemType Directory -Path views
    New-Item -ItemType File -Path views/home.ejs
    New-Item -ItemType File -Path views/profile.ejs
    ```

    Create the home page template:

    ```html views/home.ejs expandable lines theme={null}
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Auth0 Fastify Quickstart</title>
      <style>
        body {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          margin: 0;
          padding: 2rem;
          min-height: 100vh;
          display: flex;
          justify-content: center;
          align-items: center;
        }
        .container {
          background: white;
          border-radius: 20px;
          box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
          padding: 3rem;
          max-width: 500px;
          width: 100%;
          text-align: center;
        }
        h1 {
          color: #2d3748;
          font-size: 2.5rem;
          margin-bottom: 1rem;
        }
        .status {
          padding: 1rem;
          border-radius: 10px;
          margin: 1.5rem 0;
          font-size: 1.1rem;
        }
        .logged-in {
          background: #d4edda;
          color: #155724;
        }
        .logged-out {
          background: #f8d7da;
          color: #721c24;
        }
        .button {
          display: inline-block;
          padding: 1rem 2rem;
          margin: 0.5rem;
          border-radius: 10px;
          text-decoration: none;
          font-weight: 600;
          transition: all 0.3s;
        }
        .button-primary {
          background: #667eea;
          color: white;
        }
        .button-primary:hover {
          background: #5568d3;
          transform: translateY(-2px);
        }
        .button-secondary {
          background: #e53e3e;
          color: white;
        }
        .button-secondary:hover {
          background: #c53030;
          transform: translateY(-2px);
        }
      </style>
    </head>
    <body>
      <div class="container">
        <h1>🚀 Auth0 Fastify</h1>
        <div class="status <%= isAuthenticated ? 'logged-in' : 'logged-out' %>">
          <%= isAuthenticated ? '✓ You are logged in' : '✗ You are logged out' %>
        </div>
        <div>
          <% if (isAuthenticated) { %>
            <a href="/profile" class="button button-primary">View Profile</a>
            <a href="/auth/logout" class="button button-secondary">Logout</a>
          <% } else { %>
            <a href="/auth/login" class="button button-primary">Login</a>
          <% } %>
        </div>
      </div>
    </body>
    </html>
    ```

    Create the profile page template:

    ```html views/profile.ejs expandable lines theme={null}
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Profile - Auth0 Fastify</title>
      <style>
        body {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          margin: 0;
          padding: 2rem;
          min-height: 100vh;
        }
        .container {
          background: white;
          border-radius: 20px;
          box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
          padding: 3rem;
          max-width: 700px;
          margin: 0 auto;
        }
        h1 {
          color: #2d3748;
          margin-bottom: 2rem;
        }
        .profile-card {
          display: flex;
          align-items: center;
          gap: 2rem;
          padding: 2rem;
          background: #f7fafc;
          border-radius: 15px;
          margin-bottom: 2rem;
        }
        .profile-picture {
          width: 100px;
          height: 100px;
          border-radius: 50%;
          object-fit: cover;
          border: 3px solid #667eea;
        }
        .profile-info h2 {
          margin: 0 0 0.5rem 0;
          color: #2d3748;
        }
        .profile-info p {
          margin: 0;
          color: #718096;
        }
        .user-data {
          background: #f7fafc;
          padding: 1.5rem;
          border-radius: 10px;
          overflow-x: auto;
        }
        pre {
          margin: 0;
          white-space: pre-wrap;
          word-wrap: break-word;
        }
        .button {
          display: inline-block;
          padding: 0.75rem 1.5rem;
          margin-right: 1rem;
          border-radius: 10px;
          text-decoration: none;
          font-weight: 600;
          transition: all 0.3s;
        }
        .button-primary {
          background: #667eea;
          color: white;
        }
        .button-primary:hover {
          background: #5568d3;
        }
        .button-secondary {
          background: #e53e3e;
          color: white;
        }
        .button-secondary:hover {
          background: #c53030;
        }
      </style>
    </head>
    <body>
      <div class="container">
        <h1>User Profile</h1>
        <div class="profile-card">
          <img src="<%= user.picture || 'https://via.placeholder.com/100' %>" alt="Profile" class="profile-picture">
          <div class="profile-info">
            <h2><%= user.name || user.nickname || 'User' %></h2>
            <p><strong>Email:</strong> <%= user.email || 'N/A' %></p>
          </div>
        </div>
        <h3>Full User Object</h3>
        <div class="user-data">
          <pre><%= JSON.stringify(user, null, 2) %></pre>
        </div>
        <div style="margin-top: 2rem;">
          <a href="/" class="button button-primary">← Back to Home</a>
          <a href="/auth/logout" class="button button-secondary">Logout</a>
        </div>
      </div>
    </body>
    </html>
    ```
  </Step>

  <Step title="Create routes" stepNumber={6}>
    Add routes to your `server.js` file:

    ```javascript server.js expandable lines theme={null}
    import 'dotenv/config';
    import Fastify from 'fastify';
    import fastifyView from '@fastify/view';
    import fastifyAuth0 from '@auth0/auth0-fastify';
    import ejs from 'ejs';

    const fastify = Fastify({ logger: true });
    const port = process.env.PORT || 3000;

    // Register view engine
    await fastify.register(fastifyView, {
      engine: { ejs },
      root: './views',
    });

    // Register Auth0 plugin
    await fastify.register(fastifyAuth0, {
      domain: process.env.AUTH0_DOMAIN,
      clientId: process.env.AUTH0_CLIENT_ID,
      clientSecret: process.env.AUTH0_CLIENT_SECRET,
      appBaseUrl: process.env.APP_BASE_URL,
      sessionSecret: process.env.SESSION_SECRET,
    });

    // Home route - public
    fastify.get('/', async (request, reply) => {
      const session = await fastify.auth0Client.getSession({ request, reply });
      return reply.view('views/home.ejs', {
        isAuthenticated: !!session,
      });
    });

    // Profile route - protected
    fastify.get('/profile', {
      preHandler: async (request, reply) => {
        const session = await fastify.auth0Client.getSession({ request, reply });
        if (!session) {
          return reply.redirect('/auth/login');
        }
      }
    }, async (request, reply) => {
      const user = await fastify.auth0Client.getUser({ request, reply });
      return reply.view('views/profile.ejs', { user });
    });

    // Start server
    fastify.listen({ port }, (err) => {
      if (err) {
        fastify.log.error(err);
        process.exit(1);
      }
      fastify.log.info(`Server running at http://localhost:${port}`);
    });
    ```

    **Key points:**

    * The home route checks authentication status and passes it to the template
    * The profile route uses a `preHandler` to protect the route
    * `getSession()` returns the user's session or null if not authenticated
    * `getUser()` returns the authenticated user's profile information
  </Step>

  <Step title="Run your app" stepNumber={7}>
    Start the development server:

    ```shellscript theme={null}
    npm run dev
    ```

    Open your browser to [http://localhost:3000](http://localhost:3000).

    <Info>
      The `--watch` flag in Node.js 20+ automatically restarts the server when files change.
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page. When you:

  1. Click "Login" - you're redirected to Auth0's Universal Login page
  2. Complete authentication - you're redirected back to your app
  3. Visit "/profile" - you see your user information
  4. Click "Logout" - you're logged out of both your app and Auth0
</Check>

***

## Advanced Usage

<Accordion title="Calling Protected APIs with Access Tokens">
  To call external APIs that require an access token, configure the SDK with an audience:

  ```javascript server.js theme={null}
  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    appBaseUrl: process.env.APP_BASE_URL,
    sessionSecret: process.env.SESSION_SECRET,
    audience: process.env.AUTH0_AUDIENCE, // Add this
  });
  ```

  Add to your `.env` file:

  ```bash .env theme={null}
  AUTH0_AUDIENCE=https://your-api.example.com
  ```

  Then retrieve and use the access token:

  ```javascript server.js theme={null}
  fastify.get('/api-data', {
    preHandler: async (request, reply) => {
      const session = await fastify.auth0Client.getSession({ request, reply });
      if (!session) {
        return reply.redirect('/auth/login');
      }
    }
  }, async (request, reply) => {
    try {
      const { accessToken } = await fastify.auth0Client.getAccessToken({ request, reply });

      // Call your protected API
      const response = await fetch('https://your-api.example.com/data', {
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
      });

      const data = await response.json();
      return data;
    } catch (error) {
      fastify.log.error('API call failed:', error);
      return reply.status(500).send({ error: 'Failed to fetch data' });
    }
  });
  ```
</Accordion>

<Accordion title="Custom Route Paths">
  By default, Auth0 routes are mounted at `/auth/*`. You can disable auto-mounting and create custom routes:

  ```javascript server.js theme={null}
  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    appBaseUrl: process.env.APP_BASE_URL,
    sessionSecret: process.env.SESSION_SECRET,
    mountRoutes: false, // Disable auto-mounting
  });

  // Custom login route
  fastify.get('/custom-login', async (request, reply) => {
    const authorizationUrl = await fastify.auth0Client.startInteractiveLogin(
      {
        authorizationParams: {
          redirect_uri: `${process.env.APP_BASE_URL}/custom-callback`
        }
      },
      { request, reply }
    );
    return reply.redirect(authorizationUrl.href);
  });

  // Custom callback route
  fastify.get('/custom-callback', async (request, reply) => {
    await fastify.auth0Client.completeInteractiveLogin(
      new URL(request.url, process.env.APP_BASE_URL),
      { request, reply }
    );
    return reply.redirect('/');
  });

  // Custom logout route
  fastify.get('/custom-logout', async (request, reply) => {
    const logoutUrl = await fastify.auth0Client.logout(
      { returnTo: process.env.APP_BASE_URL },
      { request, reply }
    );
    return reply.redirect(logoutUrl.href);
  });
  ```

  <Note>
    Remember to update your **Allowed Callback URLs** in the Auth0 Dashboard to include your custom callback URL.
  </Note>
</Accordion>

<Accordion title="Account Linking">
  Enable users to link multiple authentication providers to a single account:

  ```javascript server.js theme={null}
  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    appBaseUrl: process.env.APP_BASE_URL,
    sessionSecret: process.env.SESSION_SECRET,
    mountConnectRoutes: true, // Enable account linking routes
  });
  ```

  This automatically creates the following routes:

  * `/auth/connect` - Link a new provider
  * `/auth/connect/callback` - Handle the linking callback
  * `/auth/unconnect` - Unlink a provider
  * `/auth/unconnect/callback` - Handle the unlinking callback

  Add linking buttons to your profile page:

  ```html views/profile.ejs theme={null}
  <div>
    <a href="/auth/connect?connection=google-oauth2">Link Google Account</a>
    <a href="/auth/unconnect?connection=google-oauth2">Unlink Google Account</a>
  </div>
  ```
</Accordion>

<Accordion title="Using TypeScript">
  Convert your project to TypeScript for better type safety:

  ```bash theme={null}
  npm install --save-dev typescript @types/node tsx
  ```

  Create a `tsconfig.json`:

  ```json tsconfig.json theme={null}
  {
    "compilerOptions": {
      "target": "ES2022",
      "module": "ESNext",
      "moduleResolution": "node",
      "esModuleInterop": true,
      "strict": true,
      "skipLibCheck": true,
      "outDir": "./dist"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules"]
  }
  ```

  Rename `server.js` to `server.ts` and add types:

  ```typescript server.ts theme={null}
  import 'dotenv/config';
  import Fastify, { FastifyRequest, FastifyReply } from 'fastify';
  import fastifyView from '@fastify/view';
  import fastifyAuth0 from '@auth0/auth0-fastify';
  import ejs from 'ejs';

  const fastify = Fastify({ logger: true });
  const port = process.env.PORT || 3000;

  await fastify.register(fastifyView, {
    engine: { ejs },
    root: './views',
  });

  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN!,
    clientId: process.env.AUTH0_CLIENT_ID!,
    clientSecret: process.env.AUTH0_CLIENT_SECRET!,
    appBaseUrl: process.env.APP_BASE_URL!,
    sessionSecret: process.env.SESSION_SECRET!,
  });

  fastify.get('/', async (request: FastifyRequest, reply: FastifyReply) => {
    const session = await fastify.auth0Client.getSession({ request, reply });
    return reply.view('views/home.ejs', {
      isAuthenticated: !!session,
    });
  });

  fastify.listen({ port: Number(port) });
  ```

  Update `package.json`:

  ```json package.json theme={null}
  {
    "scripts": {
      "dev": "tsx watch server.ts",
      "build": "tsc",
      "start": "node dist/server.js"
    }
  }
  ```
</Accordion>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues and Solutions">
    ### "Invalid state" error after login

    **Problem:** State mismatch between the authentication request and callback.

    **Solutions:**

    1. Ensure cookies are being set correctly (not blocked by browser)
    2. Verify callback URL matches exactly in Auth0 Dashboard (including `/auth/callback`)
    3. Check that `SESSION_SECRET` is set and at least 64 characters long

    ### "session is undefined" error

    **Problem:** Unable to retrieve session data.

    **Solution:** Ensure the Auth0 plugin is registered before accessing session methods:

    ```javascript theme={null}
    // ✅ Correct order
    await fastify.register(fastifyAuth0, { ... });
    fastify.get('/profile', async (request, reply) => {
      const session = await fastify.auth0Client.getSession({ request, reply });
    });

    // ❌ Wrong - plugin not awaited
    fastify.register(fastifyAuth0, { ... }); // Missing await
    fastify.get('/profile', async (request, reply) => { ... });
    ```

    ### Callback URL mismatch

    **Problem:** "Callback URL mismatch" error from Auth0.

    **Solution:**

    1. Go to your Auth0 Dashboard → Applications → Your App → Settings
    2. Add `http://localhost:3000/auth/callback` to **Allowed Callback URLs**
    3. The URL must match exactly (including the `/auth/callback` path)

    ### Environment variables not loading

    **Problem:** Configuration values are `undefined`.

    **Solution:**

    1. Ensure `import 'dotenv/config'` is at the top of your entry file
    2. Verify `.env` file is in the root directory
    3. Check for typos in variable names

    ```javascript theme={null}
    // Debug: Log config values (remove in production!)
    console.log('Config check:', {
      hasDomain: !!process.env.AUTH0_DOMAIN,
      hasClientID: !!process.env.AUTH0_CLIENT_ID,
      hasSecret: !!process.env.SESSION_SECRET,
    });
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that you have authentication working, consider exploring:

* **[Fastify API Authentication](/docs/quickstart/backend/fastify)** - Protect your API endpoints with JWT validation
* **[Customize Universal Login](https://auth0.com/docs/customize/universal-login-pages)** - Brand your login experience
* **[Add Social Connections](https://auth0.com/docs/connections/social)** - Enable Google, GitHub, and other social logins
* **[Implement MFA](https://auth0.com/docs/secure/multi-factor-authentication)** - Add multi-factor authentication

***

## Resources

* **[auth0-fastify GitHub](https://github.com/auth0/auth0-fastify)** - Source code and examples
* **[Fastify Documentation](https://fastify.dev/)** - Learn more about Fastify
* **[Auth0 Community](https://community.auth0.com/)** - Get help from the community