@clerk/express

@clerk/express

Changelog · Report a Bug · Request a Feature · Get help

Getting Started

Clerk is the easiest way to add authentication and user management to your Express application. Add sign up, sign in, and profile management to your application in minutes.

Prerequisites

• Node.js >=18.17.0 or later
• An existing Clerk application. Create your account for free.
• An existing Express application (follow their Getting started guide)

Installation

npm install @clerk/express

Usage

Navigate to the Clerk Dashboard and inside the API Keys section copy the publishable key and secret key.

Paste your keys into an .env file:

CLERK_PUBLISHABLE_KEY=pk_*******
CLERK_SECRET_KEY=sk_******

Ensure that the environment variables are loaded, for example by using dotenv at the top of your Express application:

import 'dotenv/config';

// Rest of application

clerkMiddleware()

The clerkMiddleware() function checks the request's cookies and headers for a session JWT and, if found, attaches the Auth object to the request object under the auth key.

import { clerkMiddleware } from '@clerk/express';
import express from 'express';

const app = express();

// Pass no parameters
app.use(clerkMiddleware());

// Pass options
app.use(clerkMiddleware(options));

requireAuth

The requireAuth() middleware functions similarly to clerkMiddleware(), but also protects your routes by redirecting unauthenticated users to the sign-in page.

The sign-in path will be read from the signInUrl option or the CLERK_SIGN_IN_URL environment variable if available.

import { requireAuth } from '@clerk/express';
import express from 'express';

const app = express();

// Apply centralized middleware
app.use(requireAuth());

// Apply middleware to a specific route
app.get('/protected', requireAuth(), (req, res) => {
  res.send('This is a protected route');
});

// Custom sign-in URL
app.get('/protected', requireAuth({ signInUrl: '/sign-in' }), (req, res) => {
  res.send('This is a protected route');
});

getAuth()

The getAuth() helper retrieves authentication state from the request object. See the Next.js reference documentation for more information on how to use it.

import { clerkMiddleware, getAuth } from '@clerk/express';
import express from 'express';

const app = express();

// Apply centralized middleware
app.use(clerkMiddleware());

// Protect a route based on authorization status
hasPermission = (request, response, next) => {
  const auth = getAuth(request);

  // Handle if the user is not authorized
  if (!auth.has({ permission: 'org:admin:testpermission' })) {
    return response.status(403).send('Unauthorized');
  }

  return next();
};

app.get('/path', requireAuth, hasPermission, (req, res) => res.json(req.auth));

clerkClient

Clerk's JavaScript Backend SDK exposes Clerk's Backend API resources and low-level authentication utilities for JavaScript environments. For example, if you wanted to get a list of all users in your application, instead of creating a fetch to Clerk's https://api.clerk.com/v1/users endpoint, you can use the users.getUserList() method provided by the JavaScript Backend SDK.

All resource operations are mounted as sub-APIs on the clerkClient object. See the reference documentation for more information.

import { clerkClient } from '@clerk/express';
import express from 'express';

const app = express();

app.get('/users', requireAuth, async (req, res) => {
  const users = await clerkClient.users.getUserList();
  return res.json({ users });
});

Support

You can get in touch with us in any of the following ways:

• Join our official community Discord server
• On our support page

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines and code of conduct.

Security

@clerk/express follows good practices of security, but 100% security cannot be assured.

@clerk/express is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.