Clerk Express SDK
The Clerk Express SDK is the recommended method for integrating Clerk into your Express application. Refer to the quickstart to get started.
Methods
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'
const app = express()
// Pass no parameters
app.use(clerkMiddleware())
// Pass options
app.use(clerkMiddleware(options))Options
The clerkMiddleware() function accepts these options plus the following:
- Name
clerkClient- Type
ClerkClient- Description
An instance of the ClerkClient class. This is used to interact with the Clerk API.
- Name
debug- Type
boolean- Description
A flag to enable debug mode. When enabled, the middleware will log debug information to the console.
- Name
enableHandshake- Type
boolean- Description
Enables Clerk's handshake flow, which helps verify the session state when a session JWT has expired. It issues a 307 redirect to refresh the session JWT if the user is still logged in. Defaults to
true.
requireAuth()
The requireAuth() middleware functions similarly to clerkMiddleware(), but also protects your routes by redirecting unauthenticated users to the homepage. It accepts the same options as clerkMiddleware().
You can also specify a custom sign-in URL to redirect unauthenticated users to by setting the CLERK_SIGN_IN_URL environment variable or by passing a signInUrl option to the middleware. It's recommended to set the environment variable.
import { requireAuth } from '@clerk/express'
import express from 'express'
const app = express()
const PORT = 3000
// Apply middleware to all routes
app.use(requireAuth())
// Apply middleware to a specific route - requires `process.env.CLERK_SIGN_IN_URL` to be present
app.get('/protected', requireAuth(), (req, res) => {
res.send('This is a protected route')
})
// Use a custom sign-in URL instead of the environment variable
app.get('/protected', requireAuth({ signInUrl: '/sign-in' }), (req, res) => {
res.send('This is a protected route')
})
// 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 examples on how to use the returned auth object.
The following example uses requireAuth() to protect the route based on authentication status, and then uses getAuth() to protect the route based on authorization status.
import { clerkMiddleware, getAuth, requireAuth } from '@clerk/express'
import express from 'express'
const app = express()
const PORT = 3000
// Apply centralized middleware
app.use(clerkMiddleware())
// Use `getAuth()` to protect a route based on authorization status
const hasPermission = (req, res, next) => {
const auth = getAuth(req)
// Handle if the user is not authorized
if (!auth.has({ permission: 'org:admin:example' })) {
return res.status(403).send('Forbidden')
}
return next()
}
// Use `requireAuth()` to protect this route
// If user is not authenticated, requireAuth() will redirect back to the homepage
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 the 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 the 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, requireAuth } from '@clerk/express'
import express from 'express'
const app = express()
const PORT = 3000
app.get('/user', async (req, res) => {
// Get the `userId` from the `Auth` object
const userId = req.auth.userId
if (!userId) {
return void res.status(400).json({ error: 'Error: No signed-in user' })
}
// Use the userId to get information about the user
const user = await clerkClient.users.getUser(userId)
return void res.status(200).json(user)
})
// Start the server and listen on the specified port
app.listen(PORT, () => {
console.log(`Server is running on http://localhost:${PORT}`)
})Feedback
Last updated on