Skip to content

Latest commit

 

History

History

express

README.md


@clerk/express

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

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() helper integrates Clerk authentication into your Express application. It is required to be set in the middleware chain before using other Clerk utilities, such as requireAuth and getAuth().

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

const app = express();

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

// Pass a function that will run as middleware
app.use(clerkMiddleware(handler));

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

// Pass both
app.use(clerkMiddleware(handler, options));

requireAuth

requireAuth is a middleware function that you can use to protect routes in your Express.js application. This function checks if the user is authenticated, and passes an UnauthorizedError to the next middleware if they are not.

clerkMiddleware() is required to be set in the middleware chain before this util is used.

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

const app = express();

const port = 3000;

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

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

app.use((err, req, res, next) => {
  if (err instanceof UnauthorizedError) {
    res.status(401).send('Unauthorized');
  } else {
    next(err);
  }
});

// Start the server and listen on the specified port
app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

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, ForbiddenError } from '@clerk/express';
import express from 'express';

const app = express();
const port = 3000;

// 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' })) {
    // Catch this inside an error-handling middleware
    return next(new ForbiddenError());
  }

  return next();
};

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

// Start the server and listen on the specified port
app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

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();
const port = 3000;

const users = await clerkClient.users.getUserList();

app.get('/users', requireAuth, (req, res) => res.json(users));

// Start the server and listen on the specified port
app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

Support

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

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.