Available Methods

The Clerk Node.js SDK mirrors the Backend API. Provided is a list of the available Clerk instance methods.

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

Allowlist operations

Allowlist operations are exposed by the allowlistIdentifiers sub-api (clerk.allowlistIdentifiers).

getAllowlistIdentifierList()

Retrieves the list of allowlist identifiers.

const allowlistIdentifiers =
  await clerk.allowlistIdentifiers.getAllowlistIdentifierList();

createAllowlistIdentifier(params)

Adds a new identifier to the allowlist.

Accepts an identifier parameter, which can be:

A phone number in international (E.164) format.
An email address.
A wildcard email address (*.domain.com). Use this identifier value to allow any email address in a particular email domain.

You can also control if you want to notify the owner of the identifier, by setting the notify property to true. The notify property is not available for wildcard identifiers.

const allowlistIdentifier = await createAllowlistIdentifier({
  identifier: 'test@example.com',
  notify: false,
});

deleteAllowlistIdentifier(allowlistIdentifierId)

Deletes an allowlist identifier, specified by the allowlistIdentifierId parameter. Throws an error if the allowlistIdentifierId parameter is invalid.

await deleteAllowlistIdentifier('alid_randomid');

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, if the id is valid. Throws an error otherwise.

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);

Invitation operations

Invitation operations are exposed by the invitations sub-api (clerk.invitations).

getInvitationList()

Retrieves a list of all non-revoked invitations for your application, sorted by descending creation date.

const invitations = await clerk.invitations.getInvitationList();

createInvitation(params)

Creates a new invitation for the given email address and sends the invitation email.

Keep in mind that you cannot create an invitation if there is already one for the given email address. Also, trying to create an invitation for an email address that already exists in your application will result in an error.

You can optionally pass a redirectUrl parameter when creating the invitation and the invitee will be redirected there after they click the invitation email link.

const invitation = await clerk.invitations.createInvitation({
  emailAddress: 'invite@example.com',
  redirectUrl: 'https://optionally-redirect-here',
});

revokeInvitation(invitationId)

Revokes the invitation with the provided invitationId. Throws an error if invitationId is invalid.

Revoking an invitation makes the invitation email link unusable. However, it doesn't prevent the user from signing up if they follow the sign up flow.

Only active (i.e. non-revoked) invitations can be revoked.

const invitation = await clerk.invitations.revokeInvitation('inv_some-id');

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, if the id is valid. Throws an error otherwise.

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

revokeSession(sessionId)

Revokes a session given its id, if the id is valid. Throws an error otherwise.

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. Throws an error if the provided id is invalid.

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(params?: UserListParams)

Retrieves user list:

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

Retrieves user list that is ordered and filtered by the number of results. More params can be found at the UserListParams definition.

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.

To do a broader match through a list of fields you can use the query parameter which partially matches the fields: userId, emailAddress, phoneNumber, username, web3Wallet, firstName and lastName.

// Matches users with the string `test` matched in multiple user attributes.
const usersMatchingTest = await clerk.users.getUserList({
  query: 'test',
});

getUser(userId)

Retrieves a single user by their id, if the id is valid. Throws an error otherwise.

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

getCount(params?: UserCountParams)

Retrieves the total number of users. Can be filtered down adding parameters of the type UserCountParams

const totalUsers = await clerk.users.getCount();
// Filter down
const totalUsersMatchingTest = await clerk.users.getCount({ query: 'test' });

createUser(params)

Creates a user. Your user management settings determine how you should setup your user model.

Any email address and phone number created using this method will be automatically marked as verified.

Available parameters are:

externalId - The ID of the user you use in in your external systems. Must be unique across your instance.
emailAddress[] - Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the users primary email address.
phoneNumber[] - Phone numbers that will be added to the user. Must be unique across your instance. The first phone number will be set as the users primary phone number.
username - The username to give to the user. It must be unique across your instance.
password - The plaintext password to give the user.
firstName - User's first name.
lastName - User's last name.
publicMetadata - Metadata saved on the user, that is visible to both your Frontend and Backend APIs.
privateMetadata - Metadata saved on the user, that is only visible to your Backend API.
unsafeMetadata - Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.

updateUser(userId, params)

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

The provided id must be valid, otherwise an error will be thrown.

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

Supported user attributes for update are:

Attribute	Data type
firstName	string
lastName	string
password	string
primaryEmailAddressID	string
primaryPhoneNumberID	string
publicMetadata	Record<string, unknown>
privateMetadata	Record<string, unknown>

deleteUser(userId)

Deletes a user given their id, if the id is valid. Throws an error otherwise.

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:

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

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
});