Docs

User object

The User object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each user has a unique authentication identifier which might be their email address, phone number, or a username.

A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address, but only one of them will be their primary email address. This goes for phone numbers as well; a user can have more than one, but only one phone number will be their primary. At the same time, a user can also have one or more external accounts by connecting to social providers such as Google, Apple, Facebook, and many more.

Finally, a User object holds profile data like the user's name, profile picture, and a set of metadata that can be used internally to store arbitrary information. The metadata are split into publicMetadata and privateMetadata. Both types are set from the Backend API, but public metadata can also be accessed from the Frontend API.

The ClerkJS SDK provides some helper methods on the User object to help retrieve and update user information and authentication status.

Properties

  • Name
    id
    Type
    string
    Description

    The unique identifier for the user.

  • Name
    firstName
    Type
    string | null
    Description

    The user's first name.

  • Name
    lastName
    Type
    string | null
    Description

    The user's last name.

  • Name
    fullName
    Type
    string | null
    Description

    The user's full name.

  • Name
    username
    Type
    string | null
    Description

    The user's username.

  • Name
    hasImage
    Type
    boolean
    Description

    A getter boolean to check if the user has uploaded an image or one was copied from OAuth. Returns false if Clerk is displaying an avatar for the user.

  • Name
    imageUrl
    Type
    string
    Description

    Holds the default avatar or user's uploaded profile image. Compatible with Clerk's Image Optimization.

  • Name
    passkeys
    Type
    PasskeyResource[] | null
    Description

    An array of passkeys associated with the user's account.

  • Name
    primaryEmailAddress
    Type
    EmailAddress | null
    Description

    Information about the user's primary email address.

  • Name
    primaryEmailAddressId
    Type
    string | null
    Description

    The ID for the EmailAddress that the user has set as primary.

  • Name
    emailAddresses
    Type
    EmailAddress[]
    Description

    An array of all the EmailAddress objects associated with the user. Includes the primary.

  • Name
    hasVerifiedEmailAddress
    Type
    boolean
    Description

    A getter boolean to check if the user has verified an email address.

  • Name
    primaryPhoneNumber
    Type
    PhoneNumber | null
    Description

    Information about the user's primary phone number.

  • Name
    primaryPhoneNumberId
    Type
    string | null
    Description

    The ID for the PhoneNumber that the user has set as primary.

  • Name
    phoneNumbers
    Type
    PhoneNumber[]
    Description

    An array of all the PhoneNumber objects associated with the user. Includes the primary.

  • Name
    hasVerifiedPhoneNumber
    Type
    boolean
    Description

    A getter boolean to check if the user has verified a phone number.

  • Name
    primaryWeb3WalletId
    Type
    string | null
    Description

    The ID for the Web3Wallet that the user signed up with.

  • Name
    primaryWeb3Wallet
    Type
    Web3Wallet | null
    Description

    The Web3Wallet that the user signed up with.

  • Name
    web3Wallets
    Type
    Web3Wallet[]
    Description

    An array of all the Web3Wallet objects associated with the user. Includes the primary.

  • Name
    externalAccounts
    Type
    ExternalAccount[]
    Description

    An array of all the ExternalAccount objects associated with the user via OAuth.
    Note: This includes both verified & unverified external accounts.

  • Name
    verifiedExternalAccounts
    Type
    ExternalAccount[]
    Description

    A getter for the user's list of verified external accounts.

  • Name
    unverifiedExternalAccounts
    Type
    ExternalAccount[]
    Description

    A getter for the user's list of unverified external accounts.

  • Name
    samlAccounts
    Type
    SamlAccount[]
    Description

    An experimental list of saml accounts associated with the user.

  • Name
    organizationMemberships
    Type
    OrganizationMembership[]
    Description

    A list of OrganizationMemberships representing the list of organizations the user is member with.

  • Name
    passwordEnabled
    Type
    boolean
    Description

    A boolean indicating whether the user has a password on their account.

  • Name
    totpEnabled
    Type
    boolean
    Description

    A boolean indicating whether the user has enabled TOTP by generating a TOTP secret and verifying it via an authenticator app

  • Name
    twoFactorEnabled
    Type
    boolean
    Description

    A boolean indicating whether the user has enabled two-factor authentication.

  • Name
    backupCodeEnabled
    Type
    boolean
    Description

    A boolean indicating whether the user has enabled Backup codes.

  • Name
    createOrganizationEnabled
    Type
    boolean
    Description

    A boolean indicating whether the organization creation is enabled for the user or not.

  • Name
    createOrganizationsLimit?
    Type
    number
    Description

    An integer indicating the number of organizations that can be created by the user. If the value is 0, then the user can create unlimited organizations. Default is null.

  • Name
    deleteSelfEnabled
    Type
    boolean
    Description

    A boolean indicating whether the user is able to delete their own account or not.

  • Name
    publicMetadata
    Type
    UserPublicMetadata
    Description

    Metadata that can be read from the Frontend API and Backend API and can be set only from the Backend API.

  • Name
    privateMetadata
    Type
    UserPrivateMetadata
    Description

    Metadata that can be read and set only from the Backend API.

  • Name
    unsafeMetadata
    Type
    UserUnsafeMetadata
    Description

    Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend.
    There is also an unsafeMetadata attribute in the SignUp object. The value of that field will be automatically copied to the user's unsafe metadata once the sign up is complete.

  • Name
    legalAcceptedAt
    Type
    Date
    Description

    The date when the user accepted the legal documents. null if Require express consent to legal documents is not enabled.

  • Name
    lastSignInAt
    Type
    Date | null
    Description

    The date when the user last signed in. null if the user has never signed in.

  • Name
    createdAt
    Type
    Date
    Description

    The date when the user was first created.

  • Name
    updatedAt
    Type
    Date
    Description

    The date when the user was last updated.

Methods

update()

Updates the user's attributes. Use this method to save information you collected about the user.

The appropriate settings must be enabled in the Clerk Dashboard for the user to be able to update their attributes. For example, if you want to use the update({ firstName }) method, you must enable the Name setting. It can be found on the Email, phone, username > Personal information section in the Clerk Dashboard.

function update(params: UpdateUserParams): Promise<User>

UpdateUserParams

All props below are optional.

  • Name
    username
    Type
    string
    Description

    The user's username.

  • Name
    firstName
    Type
    string
    Description

    The user's first name.

  • Name
    lastName
    Type
    string
    Description

    The user's last name.

  • Name
    primaryEmailAddressId
    Type
    string
    Description

    The ID for the EmailAddress that the user has set as primary.

  • Name
    primaryPhoneNumberId
    Type
    string
    Description

    The ID for the PhoneNumber that the user has set as primary.

  • Name
    primaryWeb3WalletId
    Type
    string
    Description

    The ID for the Web3Wallet that the user signed up with.

  • Name
    unsafeMetadata
    Type
    UserUnsafeMetadata
    Description

    Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the User object.
    Updating this value overrides the previous value; it does not merge. To perform a merge, you can pass something like { …user.unsafeMetadata, …newData } to this parameter.

Example

In the following example, the user's first name is updated to "Test".

main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

if (clerk.user) {
  await clerk.user
    .update({ firstName: 'Test' })
    .then((res) => console.log(res))
    .catch((error) => console.log('An error occurred:', error.errors))
} else {
  document.getElementById('app').innerHTML = `
    <div id="sign-in"></div>
  `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

delete()

Deletes the current user.

function delete(): Promise<void>

Example

main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

if (clerk.user) {
  await clerk.user
    .delete()
    .then((res) => console.log(res))
    .catch((error) => console.log('An error occurred:', error.errors))
} else {
  document.getElementById('app').innerHTML = `
    <div id="sign-in"></div>
  `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

setProfileImage()

Adds the user's profile image or replaces it if one already exists. This method will upload an image and associate it with the user.

function setProfileImage(params: SetProfileImageParams): Promise<ImageResource>

SetProfileImageParams

  • Name
    file
    Type
    Blob | File | string | null
    Description

    The file to set as the user's profile image, or null to remove the current image.

ImageResource
  • Name
    id?
    Type
    string
    Description

    The unique identifier of the image.

  • Name
    name
    Type
    string | null
    Description

    The name of the image.

  • Name
    publicUrl
    Type
    string | null
    Description

    The publicly accessible url for the image.

Example

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Clerk + JavaScript App</title>
  </head>
  <body>
    <div id="app"></div>

    <input type="file" id="profile-image" />
    <button id="upload-image">Upload profile image</button>

    <script type="module" src="/main.js"></script>
  </body>
</html>
main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

if (clerk.user) {
  // Update the user's profile image
  document.getElementById('upload-image').addEventListener('click', () => {
    const profileImage = document.getElementById('profile-image').files[0]
    console.log(profileImage)

    clerk.user
      .setProfileImage({ file: profileImage })
      .then((res) => console.log(res))
      .catch((error) => console.log('An error occurred:', error.errors))
  })
} else {
  document.getElementById('app').innerHTML = `
    <div id="sign-in"></div>
  `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

reload()

Reloads the user's data from Clerk's API. This method is useful when you want to refresh the user's data after performing some form of mutation.

function reload(p?: ClerkResourceReloadParams): Promise<this>

ClerkResourceReloadParams

  • Name
    rotatingTokenNonce?
    Type
    string
    Description

    A nonce to use for rotating the user's token. Used in native application OAuth flows to allow the native client to update its JWT once despite changes in its rotating token.

Example

main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

await clerk.user.reload()

getSessions()

Retrieves all active sessions for this user. This method uses a cache so a network request will only be triggered only once.

function getSessions(): Promise<SessionWithActivities[]>

Returns

TypeDescription
Promise<SessionWithActivities[]>This method returns a Promise which resolves with an array of SessionWithActivities objects.

Example

main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

if (clerk.user) {
  await clerk.user
    .getSessions()
    .then((res) => console.log(res))
    .catch((error) => console.log('An error occurred:', error.errors))
} else {
  document.getElementById('app').innerHTML = `
    <div id="sign-in"></div>
  `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

createPasskey()

Creates a passkey for the signed-in user.

function createPasskey(): Promise<PasskeyResource>

Learn more:

For an example of how to use this method, see the Passkeys custom flows documentation.

Note

When creating a passkey for a user in a multi-domain Clerk app, createPasskey() must be called from the primary domain.

isPrimaryIdentification()

A check whether or not the given resource is the primary identifier for the user.

function isPrimaryIdentification(
  ident: EmailAddressResource | PhoneNumberResource | Web3WalletResource,
): boolean

Parameters

getOrganizationInvitations()

Retrieves a list of organization invitations for the user.

function getOrganizationInvitations(
  params?: GetUserOrganizationInvitationsParams,
): Promise<ClerkPaginatedResponse<UserOrganizationInvitation>>

GetUserOrganizationInvitationsParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

  • Name
    status?
    Type
    'pending' | 'accepted' | 'revoked'
    Description

    The status an invitation can have.

Returns

TypeDescription
Promise<ClerkPaginatedResponse<UserOrganizationInvitation>>This method returns a Promise which resolves to a ClerkPaginatedResponse of UserOrganizationInvitation objects.

Example

main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

if (clerk.user) {
  await clerk.user
    .getOrganizationInvitations()
    .then((res) => console.log(res))
    .catch((error) => console.log('An error occurred:', error.errors))
} else {
  document.getElementById('app').innerHTML = `
    <div id="sign-in"></div>
  `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

getOrganizationSuggestions()

Retrieves a list of organization suggestions for the user.

function getOrganizationSuggestions(
  params?: GetUserOrganizationSuggestionsParams,
): Promise<ClerkPaginatedResponse<OrganizationSuggestion>>

GetUserOrganizationSuggestionsParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

  • Name
    status?
    Type
    'pending' | 'accepted' | ['pending' | 'accepted']
    Description

    The status an invitation can have.

Returns

TypeDescription
Promise<ClerkPaginatedResponse<OrganizationSuggestion>>This method returns a Promise which resolves to a ClerkPaginatedResponse of OrganizationSuggestion objects.

Example

main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

if (clerk.user) {
  await clerk.user
    .getOrganizationSuggestions()
    .then((res) => console.log(res))
    .catch((error) => console.log('An error occurred:', error.errors))
} else {
  document.getElementById('app').innerHTML = `
    <div id="sign-in"></div>
  `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

getOrganizationMemberships()

Retrieves a list of organization memberships for the user.

function getOrganizationMemberships(
  params?: GetUserOrganizationMembershipParams,
): Promise<ClerkPaginatedResponse<OrganizationMembershipResource>>

GetUserOrganizationMembershipParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

Returns

TypeDescription
Promise<ClerkPaginatedResponse<OrganizationSuggestion>>This method returns a Promise which resolves to a ClerkPaginatedResponse of OrganizationMembership objects.

Example

main.js
import { Clerk } from '@clerk/clerk-js'

// Initialize Clerk with your Clerk Publishable Key
const pubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(pubKey)
await clerk.load()

if (clerk.user) {
  await clerk.user
    .getOrganizationMemberships()
    .then((res) => console.log(res))
    .catch((error) => console.log('An error occurred:', error.errors))
} else {
  document.getElementById('app').innerHTML = `
    <div id="sign-in"></div>
  `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

Additional methods

In addition to the methods listed above, the User class also has the following methods:

Time-based one-time password (TOTP)

Password management

Create metadata

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on