Clerk Node.js SDK
Setting up Clerk Node.js
Create a Clerk application
You need to create a Clerk application in your Clerk Dashboard before you can set up Clerk Node.js. For more information, check out our Set up your application guide.
Install Clerk Node.js
Once a Clerk application has been created, you can install and then start using Clerk Node.js in your application. An ES module for the Clerk Node SDK is available under the @clerk/clerk-sdk-node
npm package.
Set environment variables
Below is an example of an .env.local
file.
Pro tip! If you are signed into your Clerk Dashboard, your secret key should become visible by clicking on the eye icon. Otherwise, you can find your keys in the Clerk Dashboard on the API Keys page.
Resources
All resource operations are mounted as sub-APIs on the clerkClient
object. For more information, check out the Clerk Backend SDK documentation.
Customizing resources
The following options are available for you to customize the behaviour of the clerkClient
object.
Option | Description | Default | Environment variable |
---|---|---|---|
secretKey | Server key for api.clerk.com | none | CLERK_SECRET_KEY |
apiVersion | for future use, v1 for now | v1 | CLERK_API_VERSION |
serverApiURL | for debugging / future use | https://api.clerk.com | CLERK_API_URL |
httpOptions | http client options | {} | N/A |
For every option the resolution is as follows, in order of descending precedence:
- option passed
- environment variable (if applicable)
- default
Another available environment variable is CLERK_LOGGING
. You can set its value to true
to enable additional logging that may be of use when debugging an issue.
Singleton
If you are comfortable with setting the CLERK_SECRET_KEY
environment variable and being finished, the default instance created by the SDK will suffice for your needs.
Or if you are interested only in a certain resource:
Or if you prefer a resource sub-api directly:
Setters
The following setters are available for you to change the options even after you've obtained a handle on a clerkClient
or sub-api instance:
If you have a clerkClient
handle:
clerkClient.secretKey = value;
clerkClient.serverApiUrl = value;
clerkClient.apiVersion = value;
clerkClient.httpOptions = value;
(deprecated)
If are using a sub-api handle and wish to change options on the (implicit) singleton clerkClient
instance:
setClerkSecretKey(value)
setClerkServerApiUrl(value)
setClerkApiVersion(value)
setClerkHttpOptions(value)
Custom instantiation
If you would like to customize the behavior of the SDK, you can instantiate a clerkClient
instance yourself by passing in options.
The example below shows how to create a clerkClient
instance and pass a Clerk secret key instead of setting a CLERK_SECRET_KEY
environment variable.
Multi-session applications
If Clerk is running in multi-session mode, it's important to ensure your frontend sends the Session ID that is making the request.
Our middleware will look for a query string parameter named _clerk_session_id
. If this parameter is not found, the middleware will instead choose the last active session, which may be subject to race conditions and should not be relied on for authenticating actions.
Connect/Express middlewares
The Clerk Node SDK offers two middlewares to authenticate your backend endpoints.
Manual authentication
Authenticate a particular session
Authenticate the last active session
Using the last active session is appropriate when determining the user after a navigation.
Feedback
Last updated on