Getting started with Node

Before you get started

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
Javascript
import { withSession } from '@clerk/clerk-sdk-node';
function handler(req, res) {
if (req.session) {
// do something with session.userId
} else {
// Respond with 401 or similar
}
}
export default withSession(handler);
Typescript
import { withSession, WithSessionProp } from '@clerk/clerk-sdk-node';
function handler(req WithSessionProp<NextApiRequest>, res: NextApiResponse) {
if (req.session) {
// do something with session.userId
} else {
// Respond with 401 or similar
}
}
export withSession(handler);

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
Javascript
import { requireSession } from '@clerk/clerk-sdk-node';
function handler(req, res) {
// do something with session.userId
}
export default requireSession(handler)
Typescript
import { requireSession, RequireSessionProp } from '@clerk/clerk-sdk-node';
function handler(req RequireSessionProp<NextApiRequest>, res: NextApiResponse) {
// do something with session.userId
}
export requireSession(handler)

Express middleware

import { ClerkExpressMiddleware } from '@clerk/clerk-sdk-node';
app.use(ClerkExpressMiddleware());

Manual authentication

Authenticate a particular session

Highly recommended for authenticating actions.

import { sessions } from '@clerk/clerk-sdk-node';
import Cookies from 'cookies';
// Retrieve the particular session ID from a
// query string parameter
const sessionId = req.query._clerk_session_id;
// Note: Clerk stores the clientToken in a cookie
// named "__session" for Firebase compatibility
const cookies = new Cookies(req, res);
const clientToken = cookies.get('__session');
const session = await sessions.verifySession(sessionId, clientToken);

Authenticate the last active session

Using the last active session is appropriate when determining the user after a navigation.

import { clients, sessions } from '@clerk/clerk-sdk-node';
// Note: Clerk stores the clientToken in a cookie
// named "__session" for Firebase compatibility
const cookies = new Cookies(req, res);
const clientToken = cookies.get('__session');
const client = await clients.verifyClient(sessionToken);
const sessionId = client.lastActiveSessionId;
const session = await sessions.verifySession(sessionId, clientToken);