User
The User object holds all the information for a user of your application and provides a set of methods to manage their account. Users have a unique authentication identifier which might be their email address, phone number or a username.
Users 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. Same thing with phone numbers; they can have more than one, but only one will be their primary. At the same time, they can also have one more more external accounts by connecting to OAuth providers such as Google, Apple, Facebook & many more.
Finally, User objects hold profile data like their name, a profile image and a set of metadata that can be used internally to store arbitrary information. The metadata are split into public and private. Both types are set from the Backend API, but public metadata can be accessed from the Frontend API and Backend 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 | 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. (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[] | Any 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[] | Any 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 | The Web3Wallet that the user signed up with. |
web3Wallets | Web3Wallet[] | Any 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 | Whether the user has enabled TOTP by generating a TOTP secret and verifying it via an authenticator ap |
twoFactorEnabled | boolean | Whether the user has enabled two-factor authentication. |
backupCodeEnabled | boolean | Whether the user has enabled Backup codes. |
createOrganizationEnabled | boolean | Whether the organization creation is enabled for the user or not. |
deleteSelfEnabled | boolean | 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 . |
unsafeMetadata | {[string]: any} | null | Metadata that can be read and set from the frontend. One common use case for this attribute is to use it 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 | null | The unique identifier for the PhoneNumber that the user has set as primary. |
primaryWeb3WalletId | string | null | 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. One common use case for this attribute is to use it 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 | undefined | null | 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: