Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

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.

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.

deleteAllowlistIdentifier(allowlistIdentifierId)

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

Client operations

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

getClientList()

Retrieves the list of clients:

getClient(clientId)

Retrieves a single client by its id, if the id is valid. Throws an error otherwise.

verifyClient(sessionToken)

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

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.

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.

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.

Session operations

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

getSessionList({ clientId, userId })

Retrieves the list of sessions:

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

getSession(sessionId)

Retrieves a single session by its id, if the id is valid. Throws an error otherwise.

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.

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.

User operations

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

getUserList(params?: UserListParams)

Retrieves user list:

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

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

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.

getUser(userId)

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

getCount(params?: UserCountParams)

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

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.

Supported user attributes for update are:

AttributeData type
firstNamestring
lastNamestring
passwordstring
primaryEmailAddressIDstring
primaryPhoneNumberIDstring
publicMetadataRecord<string, unknown>
privateMetadataRecord<string, unknown>

deleteUser(userId)

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

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

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:

Was this helpful?

Clerk © 2022