Docs

You are viewing an archived version of the docs.Go to latest version

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.

terminal
npm install @clerk/clerk-sdk-node
terminal
yarn add @clerk/clerk-sdk-node
terminal
pnpm add @clerk/clerk-sdk-node

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.

.env.local
CLERK_SECRET_KEY=YOUR_SECRET_KEY

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.

Note

Most options can also be set as environment variables so that you don't need to pass anything to the constructor or set it via the available setters.

OptionDescriptionDefaultEnvironment variable
secretKeyServer key for api.clerk.comnoneCLERK_SECRET_KEY
apiVersionfor future use, v1 for nowv1CLERK_API_VERSION
serverApiURLfor debugging / future usehttps://api.clerk.comCLERK_API_URL
httpOptionshttp 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.

import clerkClient from '@clerk/clerk-sdk-node';

const userList = await clerkClient.users.getUserList();

Or if you are interested only in a certain resource:

import { sessions } from '@clerk/clerk-sdk-node';

const sessionList = await sessions.getSessionList();
const pkg = require('@clerk/clerk-sdk-node');
const clerkClient = pkg.default;

clerkClient.emails
  .createEmail({ fromEmailName, subject, body, emailAddressId })
  .then((email) => console.log(email))
  .catch((error) => console.error(error));

Or if you prefer a resource sub-api directly:

const pkg = require('@clerk/clerk-sdk-node');
const { clients } = pkg;

clients
  .getClient(clientId)
  .then((client) => console.log(client))
  .catch((error) => console.error(error));

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.

import Clerk from '@clerk/clerk-sdk-node/esm/instance';

const clerkClient = Clerk({ secretKey: 'YOUR_SECRET_KEY' });

const clientList = await clerkClient.clients.getClientList();
const Clerk = require('@clerk/clerk-sdk-node/cjs/instance').default;

const clerkClient = Clerk({ secretKey: 'YOUR_SECRET_KEY' });

clerkClient.emails
    .createEmail({ fromEmailName, subject, body, emailAddressId })
    .then((email) => console.log(email))
    .catch((error) => console.error(error));

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

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';
import Cookies from 'cookies';

// 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(clientToken);
const sessionId = client.lastActiveSessionId;

const session = await sessions.verifySession(sessionId, clientToken);

Feedback

What did you think of this content?

Last updated on