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.
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.
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']
- 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
Used to verify the session token in a networkless manner. Supply the PEM public key from the API keys page -> Show JWT public key -> PEM Public Key section in the Clerk Dashboard. It's recommended to use the environment variable instead. For more information, refer to Manual JWT verification.
- Name
organizationSyncOptions?
- Type
OrganizationSyncOptions | undefined
- Description
Used to activate a specific organization or personal account based on URL path parameters. If there's a mismatch between the active organization in the session (e.g., as reported by
auth()
) and the organization indicated by the URL, the middleware will attempt to activate the organization specified in the URL.
- 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 on the API keys page in the Clerk Dashboard.
- Name
secretKey?
- Type
string
- Description
The Clerk Secret Key for your instance. This can be found on the API keys page in the Clerk Dashboard. The
CLERK_ENCRYPTION_KEY
environment variable must be set when providingsecretKey
as an option, refer to Dynamic keys.
- 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 set to
true
, the middleware will log debug information to the console. Defaults tofalse
.
- Name
enableHandshake
- Type
boolean
- Description
A flag to enable 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 totrue
.
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.
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.
clerkClient
Clerk's JavaScript Backend SDK provides access to Backend API resources and low-level authentication utilities for JavaScript environments. For example, to retrieve a list of all users in your application, you can use the users.getUserList()
method from the JavaScript Backend SDK instead of manually making a fetch request to the https://api.clerk.com/v1/users
endpoint.
All resource operations are mounted as sub-APIs on the clerkClient
object. See the reference documentation for more information.
Example: Use clerkClient
to get a user's information
The following example uses clerkClient
to get information about the currently signed-in user. If the user is authenticated, their userId
is passed to clerkClient.users.getUser()
to get the current user's User
object. If not authenticated, the request is rejected with a 401
status code.
Feedback
Last updated on