clerkMiddleware() | Next.js
clerkMiddleware()
The clerkMiddleware()
helper integrates Clerk authentication into your Next.js application through Middleware. clerkMiddleware()
is compatible with both the App and Pages routers.
Configure clerkMiddleware()
Create a middleware.ts
file at the root of your project, or in your src/
directory if you have one.
By default, clerkMiddleware
will not protect any routes. All routes are public and you must opt-in to protection for routes.
createRouteMatcher()
createRouteMatcher()
is a Clerk helper function that allows you to protect multiple routes. createRouteMatcher()
accepts an array of routes and checks if the route the user is trying to visit matches one of the routes passed to it. The paths provided to this helper can be in the same format as the paths provided to the Next Middleware matcher.
The createRouteMatcher()
helper returns a function that, if called with the req
object from the Middleware, will return true
if the user is trying to access a route that matches one of the routes passed to createRouteMatcher()
.
In the following example, createRouteMatcher()
sets all /dashboard
and /forum
routes as protected routes.
Protect routes
You can protect routes by checking either or both of the following:
- User authentication status (user is signed in or out)
- User authorization status (user has the required role or permission)
Protect routes based on user authentication status
You can protect routes based on user authentication status by checking if the user is signed in.
There are two methods that you can use:
- Use
auth().protect()
if you want to redirect unauthenticated users to the sign-in route automatically. - Use
auth().userId
if you want more control over what your app does based on user authentication status.
Protect routes based on user authorization status
You can protect routes based on user authorization status by checking if the user has the required roles or permissions.
There are two methods that you can use:
- Use
auth().protect()
if you want Clerk to return a404
if the user does not have the role or permission. - Use
auth().has()
if you want more control over what your app does based on the authorization status.
Protect multiple groups of routes
You can use more than one createRouteMatcher()
in your application if you have two or more groups of routes.
The following example uses the has()
method from Clerk's auth()
helper.
Protect all routes
To protect all routes in your application and define specific routes as public, you can use any of the above methods and simply invert the if
condition.
Debug your Middleware
If you are having issues getting your Middleware dialed in, or are trying to narrow down auth-related issues, you can use the debugging feature in clerkMiddlware()
. Add { debug: true }
to clerkMiddleware()
and you will get debug logs in your terminal.
If you would like to set up debugging for your development environment only, you can use the process.env.NODE_ENV
variable to conditionally enable debugging. For example, { debug: process.env.NODE_ENV === 'development' }
.
Combine Middleware
You can combine other Middleware with Clerk's Middleware by returning the second Middleware from clerkMiddleware()
.
clerkMiddleware()
options
The clerkMiddleware()
function accepts an optional object. The following options are available:
- Name
audience?
- Type
string | string[]
- Description
A string or list of audiences. If passed, it is checked against the
aud
claim in the token.
- Name
authorizedParties?
- Type
string[]
- Description
An allowlist of origins to verify against, to protect your application from the subdomain cookie leaking attack.
For example:['http://localhost:3000', 'https://example.com']
For more information, refer to the reference guide.
- Name
clockSkewInMs?
- Type
number
- Description
Specifies the allowed time difference (in milliseconds) between the Clerk server (which generates the token) and the clock of the user's application server when validating a token. Defaults to 5000 ms (5 seconds).
- Name
domain?
- Type
string
- Description
The domain used for satellites to inform Clerk where this application is deployed.
- Name
isSatellite?
- Type
boolean
- Description
When using Clerk's satellite feature, this should be set to
true
for secondary domains.
- Name
jwtKey?
- Type
string
- Description
An optional custom JWT key to use for session token validation.
- Name
proxyUrl?
- Type
string
- Description
Specify the URL of the proxy, if using a proxy.
- Name
signInUrl?
- Type
string
- Description
An alternative sign in URL.
- Name
signUpUrl?
- Type
string
- Description
An alternative sign up URL.
- Name
publishableKey
- Type
string
- Description
The Clerk publishable key for your instance. This can be found in your Clerk Dashboard on the API Keys page.
- Name
secretKey?
- Type
string
- Description
The Clerk secret key for your instance. This can be found in your Clerk Dashboard on the API Keys page.
CLERK_ENCRYPTION_KEY
must be defined when providingsecretKey
as an option, refer to Server-side options propagation
Server-side options propagation
The clerkMiddleware
options listed below are propagated to the Next.js application server, making them accessible for server-side helpers like auth:
signUpUrl
signInUrl
secretKey
Options are encrypted in request headers for secure server-to-server propagation. When providing a secretKey
in the options for clerkMiddleware
, the CLERK_ENCRYPTION_KEY
becomes mandatory. If no secretKey
is provided, the CLERK_ENCRYPTION_KEY
defaults to CLERK_SECRET_KEY
.
Feedback
Last updated on