Search…
Getting started with Node

Before you get started

Set CLERK_API_KEY

The Node SDK will pick automatically the CLERK_API_KEY vale from your environment variables. If your application is using .env files, create a file named .env.local in your application root if it doesn't exist already and add the above variable.
Make sure you update this variable with the API key found in your dashboard under Settings API Keys.
.env.local
1
CLERK_API_KEY=test_asdf1234
Copied!
For detailed usage to the official documentation of the Node SDK.
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 middlewares 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.

Next.js middleware

Optional session

This strategy allows you to detect whether or not there's an active session, and handle each case separately.
Javascript
Typescript
1
import { withSession } from '@clerk/clerk-sdk-node';
2
3
function handler(req, res) {
4
if (req.session) {
5
// do something with session.userId
6
} else {
7
// Respond with 401 or similar
8
}
9
}
10
11
export default withSession(handler);
Copied!
1
import { withSession, WithSessionProp } from '@clerk/clerk-sdk-node';
2
3
function handler(req WithSessionProp<NextApiRequest>, res: NextApiResponse) {
4
if (req.session) {
5
// do something with session.userId
6
} else {
7
// Respond with 401 or similar
8
}
9
}
10
11
export withSession(handler);
Copied!

Required session

This strategy mandates that a session be available. If not, it returns a 401 (no body) and your handler is never called.
Javascript
Typescript
1
import { requireSession } from '@clerk/clerk-sdk-node';
2
3
function handler(req, res) {
4
// do something with session.userId
5
}
6
7
export default requireSession(handler)
Copied!
1
import { requireSession, RequireSessionProp } from '@clerk/clerk-sdk-node';
2
3
function handler(req RequireSessionProp<NextApiRequest>, res: NextApiResponse) {
4
// do something with session.userId
5
}
6
7
export requireSession(handler)
Copied!

Express middleware

1
import { ClerkExpressMiddleware } from '@clerk/clerk-sdk-node';
2
3
app.use(ClerkExpressMiddleware());
Copied!

Manual authentication

Authenticate a particular session

Highly recommended for authenticating actions.
1
import { sessions } from '@clerk/clerk-sdk-node';
2
import Cookies from 'cookies';
3
4
// Retrieve the particular session ID from a
5
// query string parameter
6
const sessionId = req.query._clerk_session_id;
7
8
// Note: Clerk stores the clientToken in a cookie
9
// named "__session" for Firebase compatibility
10
const cookies = new Cookies(req, res);
11
const clientToken = cookies.get('__session');
12
13
const session = await sessions.verifySession(sessionId, clientToken);
Copied!

Authenticate the last active session

Using the last active session is appropriate when determining the user after a navigation.
1
import { clients, sessions } from '@clerk/clerk-sdk-node';
2
3
// Note: Clerk stores the clientToken in a cookie
4
// named "__session" for Firebase compatibility
5
const cookies = new Cookies(req, res);
6
const clientToken = cookies.get('__session');
7
8
const client = await clients.verifyClient(sessionToken);
9
const sessionId = client.lastActiveSessionId;
10
11
const session = await sessions.verifySession(sessionId, clientToken);
Copied!
Last modified 1mo ago