Clerk node SDK

Thank you for choosing Clerk for your authentication, session & user management needs!

This SDK allows you to call the Clerk server API from node / JS / TS code without having to implement the calls yourself.

To gain a better understanding of the underlying API calls the SDK makes, feel free to consult the official Clerk server API documentation.

Table of contents

• Internal implementation details
• Installation
• Resource types
• Usage
  • Options & ENV vars available
    • tl;dr
    • Full option reference
    • httpOptions
  • Singleton
    • ESM
    • CJS
    • Setters
  • Custom instantiation
    • ESM
    • CJS
  • Examples
  • Client operations
    • getClientList()
    • getClient(clientId)
    • verifyClient(sessionToken)
  • Session operations
    • getSessionList({ clientId, userId })
    • getSession(sessionId)
    • revokeSession(sessionId)
    • verifySession(sessionId, sessionToken)
  • User operations
    • getUserList()
    • getUser(userId)
    • updateUser(userId, params)
    • deleteUser(userId)
  • Email operations
    • createEmail({ fromEmailName, subject, body, emailAddressId })
  • SMS Message operations
    • createSMSMessage({ message, phoneNumberId })
• Error handling
• Express middleware
  • onError option
  • Express Error Handlers
• Next
• Troubleshooting
• Feedback / Issue reporting

Internal implementation details

This project is written in TypeScript and built with tsdx.

CJS, ESM, and UMD module builds are provided.

The http client used by the sdk is got.

All resource operations are mounted as sub-APIs on a Clerk class and return promises that either resolve with their expected resource types or reject with the error types described below.

The sub-APIs are also importable directly if you don't want to go through the Clerk class.

Installation

Using yarn:

yarn add @clerk/clerk-sdk-node

Using npm:

npm install @clerk/clerk-sdk-node --save

Resource types

The following types are of interest to the integrator:

The following types are not directly manipulable but can be passed as params to applicable calls:

Usage

Options & ENV vars available

tl;dr

If you set CLERK_API_KEY in your environment you are good to go.

Full option reference

The following options are available for you to customize the behaviour of the Clerk class.

Note that most options can also be set as ENV vars so that you don't need to pass anything to the constructor or set it via the available setters.

For every option the resolution is as follows, in order of descending precedence:

1. option passed
2. ENV var (if applicable)
3. 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.

httpOptions

The SDK allows you to pass options to the underlying http client (got) by instantiating it with an additional httpOptions object.

e.g. to pass a custom header:

const sdk = new Clerk(apiKey, { httpOptions: headers: {
        'x-unicorn': 'rainbow'
    }});

You can check the options the got client supports here.

Singleton

If you are comfortable with setting the CLERK_API_KEY ENV variable and be done with it, the default instance created by the SDK will suffice for your needs.

ESM

import clerk from '@clerk/clerk-sdk-node';
const userList = await clerk.users.getUserList();

Or if you are interested only in a certain resource:

import { sessions } from '@clerk/clerk-sdk-node';
const sessionList = await sessions.getSessionList();

CJS

const pkg = require('@clerk/clerk-sdk-node');
const clerk = pkg.default;

clerk.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 Clerk or sub-api instance:

If you have a clerk handle:

• clerk.apiKey = value;
• clerk.serverApiUrl = value;
• clerk.apiVersion = value;
• clerk.httpOptions = value;

If are using a sub-api handle and wish to change options on the (implicit) singleton Clerk instance:

• setClerkApiKey(value)
• setClerkServerApiUrl(value)
• setClerkApiVersion(value)
• setClerkHttpOptions(value)

Custom instantiation

If you would like to use more than one Clerk instance, e.g. if you are using multiple api keys or simply prefer the warm fuzzy feeling of controlling instantiation yourself:

ESM

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

const clerk = new Clerk({ apiKey: 'top-secret' });

const clientList = await clerk.clients.getClientList();

CJS

const Clerk = require('@clerk/clerk-sdk-node/instance').default;

const clerk = new Clerk({ apiKey: 'your-eyes-only' });

clerk.smsMessages
  .createSMSMessage({ message, phoneNumberId })
  .then(smsMessage => console.log(smsMessage))
  .catch(error => console.error(error));

Examples

You also consult the examples folder for further hints on usage.

Client operations

Client operations are exposed by the clients sub-api (clerk.clients).

getClientList()

Retrieves the list of clients:

const clients = await clerk.clients.getClientList();

getClient(clientId)

Retrieves a single client by its id:

const clientID = 'my-client-id';
const client = await clerk.clients.getClient(clientId);

verifyClient(sessionToken)

Retrieves a client for a given session token, if the session is active:

const sessionToken = 'my-session-token';
const client = await clerk.clients.verifyClient(sessionToken);

Session operations

Session operations are exposed by the sessions sub-api (clerk.sessions).

getSessionList({ clientId, userId })

Retrieves the list of sessions:

const sessions = await clerk.sessions.getSessionList();

Can also be filtered by a given client id, user id, or both:

const clientId = 'my-client-id';
const userId = 'my-user-id';
const sessions = await clerk.sessions.getSessionList({ clientId, sessionId });

getSession(sessionId)

Retrieves a single session by its id:

const session = await clerk.sessions.getSession(sessionId);

revokeSession(sessionId)

Revokes a session given its id. User will be signed out from the particular client the referred to:

const sessionId = 'my-session-id';
const session = await clerk.sessions.revokeSession(sessionId);

verifySession(sessionId, sessionToken)

Verifies whether a session with a given id corresponds to the provided session token:

const sessionId = 'my-session-id';
const sessionToken = 'my-session-token';
const session = await clerk.sessions.verifySession(sessionId, sessionToken);

User operations

User operations are exposed by the users sub-api (clerk.users).

getUserList()

Retrieves user list:

const users = await clerk.users.getUserList();

Retrieves user list that is ordered and filtered by the number of results:

const sessions = await clerk.users.getUserList({
  orderBy: '-created_at',
  limit: 10,
});

Retrieves user list that is filtered by the given email addresses and phone numbers:

const emailAddress = ['email1@clerk.dev', 'email2@clerk.dev'];
const phoneNumber = ['+12025550108'];
const sessions = await clerk.users.getUserList({ emailAddress, phoneNumber });

If these filters are included, the response will contain only users that own any of these emails and/or phone numbers.

getUser(userId)

Retrieves a single user by their id:

const userId = 'my-user-id';
const user = await clerk.users.getUser(userId);

updateUser(userId, params)

Updates a user with a given id with attribute values provided in a params object:

const userId = 'my-user-id';
const params = { firstName = 'John', lastName: 'Wick' }; // See below for all supported keys
const user = await clerk.users.update(userId, params);

Supported user attributes for update are:

deleteUser(userId)

Deletes a user given their id:

const userId = 'my-user-id';
const user = await clerk.users.deleteUser(userId);

Email operations

Email operations are exposed by the emails sub-api (clerk.emails).

createEmail({ fromEmailName, subject, body, emailAddressId })

Sends an email message to an email address id belonging to another user:

const fromEmailName = 'sales'; // i.e. the "sales" in sales@example.com
const subject = 'Free tacos';
const body = 'Join us via Zoom for remote Taco Tuesday!';
const emailAddressId = 'recipient-email-address-id';
const email = await clerk.emails.createEmail({
  fromEmailName,
  subject,
  body,
  emailAddressId,
});

SMS Message operations

SMS message operations are exposed by the smsMessages sub-api (clerk.smsMessages).

createSMSMessage({ message, phoneNumberId })

Sends an SMS message to a phone number id belonging to another user:

const message = 'All glory to the Hypnotoad!';
const phoneNumberId = 'recipient-phone-number-id';
const smsMessage = await clerk.smsMessages.createSMSMessage({
  message,
  phoneNumberId,
});

Error handling

The error handling is pretty generic at the moment but more fine-grained errors are coming soon ™.

Express middleware

For usage with Express, this package also exports ClerkExpressWithSession (lax) & ClerkExpressRequireSession (strict) middlewares that can be used in the standard manner:

import { ClerkWithSession } from 'sdk-server-node';

// Initialize express app the usual way

app.use(ClerkWithSession());

The ClerkWithSession middleware will set the Clerk session on the request object as req.session and then call the next middleware.

You can then implement your own logic for handling a logged-in or logged-out user in your express endpoints or custom middleware, depending on whether your users are trying to access a public or protected resource.

If you want to use the express middleware of your custom Clerk instance, you can use:

app.use(clerk.expressWithSession());

Where clerk is your own instance.

If you prefer that the middleware renders a 401 (Unauthenticated) itself, you can use the following variant instead:

import { ClerkExpressRequireSession } from 'sdk-server-node';

app.use(ClerkExpressRequireSession());

onError option

The Express middleware supports an options object as an optional argument. The only key currently supported is onError for providing your own error handler.

The onError function, if provided, should take an Error argument (onError(error)).

Depending on the return value, it can affect the behavior of the middleware as follows:

• If an Error is returned, the middleware will call next(err) with that error. If the err has a statusCode it will indicate to Express what HTTP code the response should have.
• If anything other than an Error is returned (or nothing is returned at all), then the middleware will call next() without arguments

The default implementations unless overridden are:

// defaultOnError swallows the error
defaultOnError(error: Error) {
  console.error(error.message);
}

// strictOnError returns the error so that Express will halt the request chain
strictOnError(error: Error) {
  console.error(error.message);
  return error;
}

defaultOnError is used in the lax middleware variant and strictOnError in the strict variant.

Express Error Handlers

Not to be confused with the onError option mentioned above, Express comes with a default error handler for errors encountered in the middleware chain.

Developers can also implement their own custom error handlers as detailed here.

An example error handler can be found in the Express examples folder:

// Note: this is just a sample errorHandler that pipes clerk server errors through to your API responses
// You will want to apply different handling in your own app to avoid exposing too much info to the client
function errorHandler(err, req, res, next) {
  const statusCode = err.statusCode || 500;
  const body = err.data || { error: err.message };

  res.status(statusCode).json(body);
}

If you are using the strict middleware variant, the err pass to your error handler will contain enough context for you to respond as you deem fit.

Next

The current package also offers a way of making your Next.js api middleware aware of the Clerk Session.

You can define your handler function with the usual signature (function handler(req, res) {}) then wrap it with withSession:

import { withSession, WithSessionProp } from '@clerk/clerk-sdk-node';

Note: Since the request will be extended with a session property, the signature of your handler in TypeScript would be:

function handler(req: WithSessionProp<NextApiRequest>, res: NextApiResponse) {
    if (req.session) {
        // do something with session.userId
    } else {
        // Respond with 401 or similar
    }
}

export withSession(handler);

You can also pass an onError handler to the underlying Express middleware that is called (see previous section):

export withSession(handler, { clerk, onError: error => console.log(error) });

In case you would like the request to be rejected automatically when no session exists, without having to implement such logic yourself, you can opt for the stricter variant:

import clerk, {
  requireSession,
  RequireSessionProp,
} from '@clerk/clerk-sdk-node';

In this case your handler can be even simpler because the existence of the session can be assumed, otherwise the execution will never reach your handler:

function handler(req: RequireSessionProp<NextApiRequest>, res: NextApiResponse) {
    // do something with session.userId
}

export requireSession(handler, { clerk, onError });

Note that by default the error returned will be the Clerk server error encountered (or in case of misconfiguration, the error raised by the SDK itself).

If you wish to have more control over what error code & message to respond with in this case, it's recommended to implement your own error class & handler as follows:

export class HttpError extends Error {
  statusCode: number;

  constructor(message: string, statusCode: number) {
    super(message);

    // Set the prototype explicitly.
    Object.setPrototypeOf(this, HttpError.prototype);

    this.statusCode = statusCode;
  }
}

export function onError(error: Error) {
  // Ignore passed error, return a 401
  console.log(error);
  return new HttpError('Unauthorized', 401);
}

The aforementioned usage pertains to the singleton case. If you would like to use a Clerk instance you instantiated yourself (e.g. named clerk), you can use the following syntax instead:

export clerk.withSession(handler);
// OR
export clerk.requireSession(handler);

Troubleshooting

Especially when using the middlewares, a number of common issues may occur.

Please consult the following check-list for some potential quick fixes:

• Is the CLERK_API_KEY set in your environment?
• In case you are using multiple Clerk apps or instances thereof (i.e. development, staging, production), ensure you are using the API key for the correct Clerk instance.
• If you are handling instantiation of the Clerk object yourself, are you passing your server API key to the constructor via the apiKey option?
• In development mode, do your frontend & API reside on the same domain? Unless the clerk __session is sent to your API server, the SDK will fail to authenticate your user.
• If you are still experiencing issues, it is advisable to set the CLERK_LOGGING environment variable to true to get additional logging output that may help identify the issue.

Note: The strict middleware variants (i.e. the "require session" variants) will produce an erroneous response if the user is not signed in. Please ensure you are not mounting them on routes that are meant to be publicly accessible.

Publishing

There are two ways to publish the package:

1. Run the publishPackage script supplying the bump type you wish to do and the changes will happen automatically. Supported ones are major|minor|patch. E.g. yarn publishPackage minor.
2. Run the steps described in the publish script manually step by step.

Feedback / Issue reporting

Please report issues or open feature request in the github issue section.