Fastify Authentication

Easily add authentication focused on security, speed, and DX to your Fastify server.

Overview

Clerk is the easiest way to add authentication and user management to your Fastify server. This guide will walk you through the necessary steps to install and use Clerk in a basic Fastify-powered application.

After following this guide, you should have a working Fastify app with public and private routes, authenticated using the `clerkPlugin` and `getAuth` helpers.

Looking for a quickstart? We created clerk-fastify-starter to show you how to add Clerk to your project.

Before you start

You need to create a Clerk Application in your Clerk Dashboard before you can set up Clerk React. For more information, check out our Setup your application guide.

Creating a new Fastify app

Start by creating a new Fastify application - for more details, follow the official Fastify "Getting-Started" guide.

npm i fastify

Installing Clerk

Install the `@clerk/fastify` package. This package can be used with ESM and CJS imports.

1
npm install @clerk/fastify

Setting Environment Keys

Two environment variables for the Clerk SDK can be set. Below is an example of your .env file. To get the respective keys, go to the API Keys page in the Clerk dashboard.

.env.local1

You can also pass these keys into the Clerk plugin directly.

Most applications rely on environment variables, so your app's infrastructure for reading them should already be set up. For demonstration purposes, in this example, we will use `dontenv`:

1
npm install dotenv
2
npm install -D types/dotenv

Adding `clerkPlugin`

Adding Clerk is pretty straightforward. You only need to import and register the `clerkPlugin` helper, as shown below.

1
import * as dotenv from "dotenv";
2

3
dotenv.config();
4

5
import Fastify from "fastify";
6
import { clerkClient, clerkPlugin, getAuth } from "@clerk/fastify";
7

8
const fastify = Fastify({ logger: true });
9

10
/**
11
 * Register the Clerk plugin globally.
12
 * By default, Clerk will initialise using the API keys from the environment if found.
13
 *
14
 * If you prefer to pass the keys to the plugin explicitly, see `src/using-runtime-keys.ts`
15
 * If you prefer to register the plugin for specific routes only, see `src/authenticating-specific-routes.ts`
16
 */
17
fastify.register(clerkPlugin);
18

19
const start = async () => {
20
  try {
21
    await fastify.listen({ port: 3000 });
22
  } catch (err) {
23
    fastify.log.error(err);
24
    process.exit(1);
25
  }
26
};
27

28
start();
29

Accessing the auth state using `getAuth`

Next, add a new route and call the `getAuth`helper as shown below.

1
import * as dotenv from "dotenv";
2

3
dotenv.config();
4

5
import Fastify from "fastify";
6
import { clerkClient, clerkPlugin, getAuth } from "@clerk/fastify";
7

8
const fastify = Fastify({ logger: true });
9

10
fastify.register(clerkPlugin);
11

12
fastify.get("/", async (req, reply) => {
13
  /**
14
   * Access the auth state for this request.
15
   * In this example, we use the userId to load the whole User object
16
   * from the Clerk servers
17
   */
18
  const { userId } = getAuth(req);
19
  const user = userId ? await clerkClient.users.getUser(userId) : null;
20
  return { user };
21
});
22

23
const start = async () => {
24
  try {
25
    await fastify.listen({ port: 3000 });
26
  } catch (err) {
27
    fastify.log.error(err);
28
    process.exit(1);
29
  }
30
};
31

32
start();
33

Requiring authentication

The easiest way to require authentication before accessing a protected route is to check wether a session exists within the route handler, as shown below.

1
fastify.get("/protected", async (request, reply) => {
2
  const { userId } = getAuth(request);
3
  if (!userId) {
4
    return reply.code(403).send();
5
  }
6

7
  const user = userId ? await clerkClient.users.getUser(userId) : null;
8
  return { user };
9
});

Using Clerk for specific routes only

Fastify provides an easy way to register plugins for specific scopes only using the `register` helper. In the following example, we split our routes into two different fastify plugins - but we only register Clerk in one of them.

1
import * as dotenv from "dotenv";
2

3
dotenv.config();
4

5

6
import Fastify, { FastifyPluginCallback } from "fastify";
7
import { clerkClient, clerkPlugin, getAuth } from "@clerk/fastify";
8

9
const fastify = Fastify({ logger: true });
10

11
/**
12
 * Register Clerk only for a subset of your routes
13
 */
14
const protectedRoutes: FastifyPluginCallback = (instance, opts, done) => {
15
  instance.register(clerkPlugin);
16
  instance.get("/protected", async (request, reply) => {
17
    const { userId } = getAuth(request);
18
    if (!userId) {
19
      return reply.code(403).send();
20
    }
21

22
    const user = userId ? await clerkClient.users.getUser(userId) : null;
23
    return { user };
24
  });
25
  done();
26
};
27

28
const publicRoutes: FastifyPluginCallback = (instance, opts, done) => {
29
  instance.get("/", async (request, reply) => {
30
    return { message: "This is a public endpoint. Request /protected to test the Clerk auth middleware" };
31
  });
32
  done();
33
};
34

35
/**
36
 * Register your routes as you normally would
37
 */
38
fastify.register(protectedRoutes);
39
fastify.register(publicRoutes);
40

41
const start = async () => {
42
  try {
43
    await fastify.listen({ port: 3000 });
44
  } catch (err) {
45
    fastify.log.error(err);
46
    process.exit(1);
47
  }
48
};
49

50
start();
51