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 OAuth 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
A 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 unique identifier 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 unique identifier 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 unique identifier 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
OrganizationMembership
s 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 isnull
.
- Name
deleteSelfEnabled
- Type
boolean
- Description
A boolean indicating whether the user is able to delete their own account or not.
- Name
publicMetadata
- Type
{[string]: any} | null
- 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
{[string]: any} | null
- Description
Metadata that can be read and set only from the Backend API.
- Name
unsafeMetadata
- Type
{[string]: any} | null
- 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.
Please note that there is also anunsafeMetadata
attribute in theSignUp
object. The value of that field will be automatically copied to the user's unsafe metadata once the sign up is complete.
- Name
lastSignInAt
- Type
Date
- Description
Date when the user last signed in. May be empty if the user has never signed in.
- Name
createdAt
- Type
Date
- Description
Date when the user was first created.
- Name
updatedAt
- Type
Date
- Description
Date of the last time the user was 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 in the the Clerk Dashboard under User & Authentication > Email, Phone, Username > Personal information.
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 unique identifier for the
EmailAddress
that the user has set as primary.
- Name
primaryPhoneNumberId
- Type
string
- Description
The unique identifier for the
PhoneNumber
that the user has set as primary.
- Name
primaryWeb3WalletId
- Type
string
- Description
The unique identifier for the
Web3Wallet
that the user signed up with.
- Name
unsafeMetadata
- Type
{[string]: any} | null
- 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".
delete()
Deletes the current user.
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.
- 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.
For the following example, your HTML file should look like this:
And your JavaScript file should look like this:
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.
- 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.
getSessions()
Retrieves all active sessions for this user. This method uses a cache so a network request will only be triggered only once.
Returns
Type | Description |
---|---|
Promise<SessionWithActivities[]> | This method returns a Promise which resolves with an array of SessionWithActivities objects. |
Example
createPasskey()
Creates a passkey for the signed-in user.
Learn more:
For an example of how to use this method, see the Passkeys custom flows documentation.
isPrimaryIdentification()
A check whether or not the given resource is the primary identifier for the user.
- Name
ident
- Type
EmailAddress | PhoneNumber | Web3Wallet
- Description
The resource checked against the user to see if it is the primary identifier.
getOrganizationInvitations()
Retrieves a list of organization invitations for the user.
- 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
Type | Description |
---|---|
Promise<ClerkPaginatedResponse<UserOrganizationInvitation>> | This method returns a Promise which resolves to a ClerkPaginatedResponse of UserOrganizationInvitation objects. |
Example
getOrganizationSuggestions()
Retrieves a list of organization suggestions for the user.
- 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
Type | Description |
---|---|
Promise<ClerkPaginatedResponse<OrganizationSuggestion>> | This method returns a Promise which resolves to a ClerkPaginatedResponse of OrganizationSuggestion objects. |
Example
getOrganizationMemberships()
Retrieves a list of organization memberships for the user.
- 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
Type | Description |
---|---|
Promise<ClerkPaginatedResponse<OrganizationSuggestion>> | This method returns a Promise which resolves to a ClerkPaginatedResponse of OrganizationMembership objects. |
Example
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
Last updated on