Skip to content

Latest commit

 

History

History
671 lines (468 loc) · 23.1 KB

API.md

File metadata and controls

671 lines (468 loc) · 23.1 KB

Clerk Backend API Resource reference

Reference of the methods supported in the Clerk Backend API wrapper. API reference

! All methods should be called from a [ClerkBackendApi](./src/api/ClerkBackendApi.ts) instance.

Allowlist operations

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

getAllowlistIdentifierList()

Retrieves the list of allowlist identifiers.

const allowlistIdentifiers = await clerkAPI.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 clerkAPI.allowlistIdentifiers.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 clerkAPI.allowlistIdentifiers.deleteAllowlistIdentifier('alid_randomid');

Client operations

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

getClientList()

Retrieves the list of clients:

const clients = await clerkAPI.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 clerkAPI.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 clerkAPI.clients.verifyClient(sessionToken);

Invitation operations

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

getInvitationList()

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

const invitations = await clerkAPI.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 clerkAPI.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 clerkAPI.invitations.revokeInvitation('inv_some-id');

Organization operations

Organization operations are exposed by the organizations sub-api (clerkAPI.organizations).

getOrganizationList()

Retrieves a list of organizations for an instance.

The instance is determined by the API key you've provided when configuring the API. You can either set the CLERK_API_KEY environment variable, or provide the apiKey property explicitly when configuring the API client.

Results can be paginated by providing an optional limit and offset pair of parameters.

Results will be ordered by descending creation date. Most recent organizations will be first in the list.

const organizations = await clerkAPI.organizations.getOrganizationList();

createOrganization(params)

Creates a new organization with the given name and optional slug.

You need to provide the user ID who is going to be the organization owner. The user will become an administrator for the organization.

Available parameters are:

  • name The name for the organization.
  • createdBy The ID of the user who is going to be the organization administrator.
  • publicMetadata Metadata saved on the organization, that is visible to both your Frontend and Backend APIs.
  • privateMetadata Metadata saved on the organization, that is only visible to your Backend API.
const organization = await clerkAPI.organizations.createOrganization({
  name: 'Acme Inc',
  slug: 'acme-inc',
  createdBy: 'user_1o4q123qMeCkKKIXcA9h8',
});

getOrganization(params)

Fetch an organization whose ID or slug matches the one provided in the parameters.

The method accepts either the organization ID or slug in the parameters, but not both at the same time. See the snippet below for a usage example.

The instance that the organization belongs to is determined by the API key you've provided when configuring the API. You can either set the CLERK_API_KEY environment variable, or provide the apiKey property explicitly when configuring the API client.

Available parameters:

  • organizationId The ID of the organization.
  • slug Alternatively, you can provide the slug of the organization.
const organizationBySlug = await clerkAPI.organizations.getOrganization({
  slug: 'acme-inc',
});

const organizationById = await clerkAPI.organizations.getOrganization({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
});

updateOrganization(organizationId, params)

Update the organization specified by organizationId.

Available parameters are:

  • name The name for the organization.
const organization = await clerkAPI.organizations.updateOrganization('org_1o4q123qMeCkKKIXcA9h8', {
  name: 'Acme Inc',
});

updateOrganizationMetadata(organizationId, params)

Update an organization's metadata attributes by merging existing values with the provided parameters.

You can remove metadata keys at any level by setting their value to null.

Available parameters are:

  • publicMetadata Metadata saved on the organization, that is visible to both your Frontend and Backend APIs.
  • privateMetadata Metadata saved on the organization, that is only visible to your Backend API.
const organization = await clerkAPI.organizations.updateOrganizationMetadata('org_1o4q123qMeCkKKIXcA9h8', {
  publicMetadata: { color: 'blue' },
  privateMetadata: { sandbox_mode: true },
});

deleteOrganization(organizationId)

Delete an organization with the provided organizationId. This action cannot be undone.

await clerkAPI.organizations.deleteOrganization(organizationId);

getPendingOrganizationInvitationList(params)

Retrieve a list of pending organization invitations for the organization specified by organizationId.

The method supports pagination via optional limit and offset parameters. The method parameters are:

  • organizationId The unique ID of the organization to retrieve the pending invitations for
  • limit Optionally put a limit on the number of results returned
  • offset Optionally skip some results
const invitations = await clerkAPI.organizations.getPendingOrganizationInvitationList({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
});

createOrganizationInvitation(params)

Create an invitation to join an organization and send an email to the email address of the invited member.

You must pass the ID of the user that invites the new member as inviterUserId. The inviter user must be an administrator in the organization.

You can optionally pass metadata for the organization invitation with the publicMetadata field. These metadata will be accessible from both the Frontend and the Backend. Once the invitation is accepted, the metadata will be transferred to the newly created organization membership.

Available parameters:

  • organizationId The unique ID of the organization the invitation is about.
  • emailAddress The email address of the member that's going to be invited to join the organization.
  • role The new member's role in the organization.
  • inviterUserId The ID of the organization administrator that invites the new member.
  • redirectUrl An optional URL to redirect to after the invited member clicks the link from the invitation email.
  • publicMetadata Optionally pass metadata for the organization invitation which will be visible to both your Frontend and Backend.
const invitation = await clerkAPI.organizations.createOrganizationInvitation({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
  inviterUserId: 'user_1o4q123qMeCkKKIXcA9h8',
  emailAddress: 'invited@example.org',
  role: 'basic_member',
  redirectUrl: 'https://example.org',
});

revokeOrganizationInvitation(params)

Revoke a pending organization invitation for the organization specified by organizationId.

The requesting user must be an administrator in the organization.

The method parameters are:

  • organizationId The ID of the organization that the invitation belongs to.
  • invitationId The ID of the pending organization invitation to be revoked.
  • requestingUserId The ID of the user that revokes the invitation. Must be an administrator.
const invitation = await clerkAPI.organizations.revokeOrganizationInvitation({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
  invitationId: 'orginv_4o4q9883qMeFggTKIXcAArr',
  requestingUserId: 'user_1o4q123qMeCkKKIXcA9h8',
});

getOrganizationMembershipList(params)

Get a list of memberships for the organization with the provided organizationId.

The method supports pagination via optional limit and offset parameters. The method parameters are:

  • organizationId The unique ID of the organization to retrieve the memberships for
  • limit Optionally put a limit on the number of results returned
  • offset Optionally skip some results
const memberships = await clerkAPI.organizations.getOrganizationMemberships({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
});

createOrganizationMembership(params)

Create a membership for the organization specified by organizationId. Effectively adds a user to an organization.

Available parameters:

  • organizationId The ID of the organization to add a member to.
  • userId The ID of the user that will be added to the organization.
  • role The role of the new member in the organization
const membership = await clerkAPI.organizations.createOrganizationMembership({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
  userId: 'user_1o4q123qMeCkKKIXcA9h8',
  role: 'basic_member',
});

updateOrganizationMembership(params)

Updates the organization membership of the user with userId for the organization with organizationId.

Available parameters:

  • organizationId The ID of the organization that the membership belongs to.
  • userId The ID of the user who's a member of the organization.
  • role The role of the organization member.
const membership = await clerkAPI.organizations.updateOrganizationMembership({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
  userId: 'user_1o4q123qMeCkKKIXcA9h8',
  role: 'admin',
});

deleteOrganizationMembership(params)

Deletes an organization membership, specified by the organizationId and userId parameters.

const membership = await clerkAPI.organizations.deleteOrganizationMembership({
  organizationId: 'org_1o4q123qMeCkKKIXcA9h8',
  userId: 'user_1o4q123qMeCkKKIXcA9h8',
});

Redirect URLs operations

Redirect URLs endpoints are used to whitelist URLs for native application authentication flows such as OAuth sign-ins and sign-ups in React Native and Expo.

Redirect URL operations are exposed by the redirectUrls sub-api (clerkAPI.redirectUrls).

createRedirectUrl({ url })

Creates a new redirect URL:

const redirectUrl = await clerkAPI.redirectUrls.createRedirectUrl({ url });

getRedirectUrlList()

Get the list of all redirect URLs:

const redirectUrlList = await clerkAPI.redirectUrls.getRedirectUrlList();

getRedirectUrl(redirectUrlId)

Retrieve a redirect URL:

const redirectUrl = await clerkAPI.redirectUrls.getRedirectUrl('redirect_url_test');

deleteRedirectUrl(redirectUrlId)

Delete a redirect URL:

await clerkAPI.redirectUrls.deleteRedirectUrl('redirect_url_test');

Session operations

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

getSessionList({ clientId, userId })

Retrieves the list of sessions:

const sessions = await clerkAPI.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 clerkAPI.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 clerkAPI.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 clerkAPI.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 clerkAPI.sessions.verifySession(sessionId, sessionToken);

Sign in token operations

Generate a token for an existing user to sign in without him needing to apply any first-factor type authentication.

Second-factor type inputs would still need to be filled.

createSignInToken(params)

Creates a sign in token:

const signInToken = await clerkAPI.signInTokens.createSignInToken({ userId: 'user_test_id', expiresInSeconds: 60 });

revokeSignInToken(signInTokenId)

Revokes an issued sign in token.

await clerkAPI.signInTokens.revokeSignInToken('token_test_id');

User operations

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

getUserList()

Retrieves user list:

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

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

const sessions = await clerkAPI.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, if the id is valid. Throws an error otherwise.

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

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.
  • totpSecret User's secret for TOTP. Useful while migrating users with enabled 2FA Authenticator Apps.
  • backupCodes User's backup codes. Useful while migrating users with already existed 2FA backup codes.
  • 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 below for all supported keys
const user = await clerkAPI.users.update(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>
totpSecret string
backupCodes string[]

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 clerkAPI.users.deleteUser(userId);

disableUserMFA(userId)

Disables all MFA methods of a user given their id. Throws an error otherwise.

const userId = 'my-user-id';
await clerkAPI.users.disableUserMFA(userId);

getOrganizationMembershipList(params)

Get a list of organization memberships for the user with the provided userId.

The method supports pagination via optional limit and offset parameters. The method parameters are:

  • userId The unique ID of the user to retrieve organization memberships for
  • limit Optionally put a limit on the number of results returned
  • offset Optionally skip some results
const memberships = await clerkAPI.users.getOrganizationMemberships({
  userId: 'user_1o4q123qMeCkKKIXcA9h8',
});

Email operations

Email operations are exposed by the emails sub-api (clerkAPI.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 clerkAPI.emails.createEmail({
  fromEmailName,
  subject,
  body,
  emailAddressId,
});

SMS Message operations

SMS message operations are exposed by the smsMessages sub-api (clerkAPI.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 clerkAPI.smsMessages.createSMSMessage({
  message,
  phoneNumberId,
});

Error handling

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