User
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.
Attributes
| Name | Type | Description |
|---|---|---|
id | string | A unique identifier for the user. |
firstName | string | null | The user's first name. |
lastName | string | null | The user's last name. |
fullName | string | null | The user's full name. |
username | string | null | The user's username. |
imageUrl | string | Holds the users profile image or avatar. |
profileImageUrl | string | null | The URL for the user's profile image. This property is deprecated in favor of image_url |
primaryEmailAddress | EmailAddress | null | Information about the user's primary email address. |
primaryEmailAddressId | string | null | The unique identifier for the EmailAddress that the user has set as primary. |
emailAddresses | EmailAddress[] | An array of all the EmailAddress objects associated with the user. Includes the primary. |
hasVerifiedEmailAddress | boolean | A getter boolean to check if the user has verified an email address. |
primaryPhoneNumber | PhoneNumber | null | Information about the user's primary phone number. |
primaryPhoneNumberId | string | null | The unique identifier for the PhoneNumber that the user has set as primary. |
phoneNumbers | PhoneNumber[] | An array of all the PhoneNumber objects associated with the user. Includes the primary. |
hasVerifiedPhoneNumber | boolean | A getter boolean to check if the user has verified a phone number. |
primaryWeb3WalletId | string | null | The unique identifier for the Web3Wallet that the user signed up with. |
primaryWeb3Wallet | Web3Wallet | null | The Web3Wallet that the user signed up with. |
web3Wallets | Web3Wallet[] | An array of all the Web3Wallet objects associated with the user. Includes the primary. |
externalAccounts | ExternalAccount[] | An array of all the ExternalAccount objects associated with the user via OAuth.Note: This includes both verified & unverified external accounts. |
verifiedExternalAccounts | ExternalAccount[] | A getter for the user's list of verified external accounts. |
unverifiedExternalAccounts | ExternalAccount[] | A getter for the user's list of unverified external accounts. |
samlAccounts | SamlAccount[] | An experimental list of saml accounts associated with the user. |
organizationMemberships | OrganizationMembership[] | A list of OrganizationMemberships representing the list of organizations the user is member with. |
passwordEnabled | boolean | A boolean indicating whether the user has a password on their account. |
totpEnabled | boolean | A boolean indicating whether the user has enabled TOTP by generating a TOTP secret and verifying it via an authenticator ap |
twoFactorEnabled | boolean | A boolean indicating whether the user has enabled two-factor authentication. |
backupCodeEnabled | boolean | A boolean indicating whether the user has enabled Backup codes. |
createOrganizationEnabled | boolean | A boolean indicating whether the organization creation is enabled for the user or not. |
deleteSelfEnabled | boolean | A boolean indicating whether the user is able to delete their own account or not. |
publicMetadata | {[string]: any} | null | Metadata that can be read from the Frontend API and Backend API and can be set only from the Backend API . |
privateMetadata | {[string]: any} | null | Metadata that can be read and set only from the Backend API. |
unsafeMetadata | {[string]: any} | null | 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 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. |
lastSignInAt | Date | Date when the user last signed in. May be empty if the user has never signed in. |
createdAt | Date | Date when the user was first created. |
updatedAt | Date | Date of the last time the user was updated. |
Methods
update()
function update: (params: UpdateUserParams) => Promise<User>;
Updates the user's attributes. Use this method to save information you collected about the user.
UpdateUserParams
| Name | Type | Description |
|---|---|---|
username | string | The user's username. |
password | string | The user's password. This property is deprecated. This will be removed in the next major version. Please use updatePassword(params) instead. |
firstName | string | The user's first name. |
lastName | string | The user's last name. |
primaryEmailAddressId | string | The unique identifier for the EmailAddress that the user has set as primary. |
primaryPhoneNumberId | string | The unique identifier for the PhoneNumber that the user has set as primary. |
primaryWeb3WalletId | string | The unique identifier for the Web3Wallet that the user signed up with. |
unsafeMetadata | {[string]: any} | null | 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 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. |
delete()
function delete: () => Promise<void>;
Delete the current user.
setProfileImage()
function setProfileImage: (params: SetProfileImageParams) => Promise<ImageResource>;
Add the user's profile image or replace it if one already exists. This method will upload an image and associate it with the user.
SetProfileImageParams
| Name | Type | Description |
|---|---|---|
file | Blob | File | string | null | The file to set as the user's profile image. |
Returns
| Type | Description |
|---|---|
Promise<ImageResource> | The uploaded image. |
ImageResource
| Name | Type | Description |
|---|---|---|
id | string | The unique identifier of the image. |
name | string | null | The name of the image. |
publicUrl | string | null | The publically accessible url for the image. |
getSessions()
function getSessions: () => Promise<SessionWithActivities[]>;
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[]> | The list of active user sessions. |
isPrimaryIdentification()
function isPrimaryIdentification: (ident: EmailAddressResource | PhoneNumberResource | Web3WalletResource) => boolean;
A check whether or not the given resource is the primary identifier for the user.
Params
| Name | Type | Description |
|---|---|---|
ident | EmailAddress | PhoneNumber | Web3Wallet | The resource checked against the user to see if it is the primary identifier. |
Additional methods
In addition to the methods listed above, the User class also has the following methods: