User

The User object contains the user's account information.

Overview

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.
profileImageUrl	string \| null	The URL for the user's profile image.
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	emailAddresses[]	Any array of all the EmailAddress objects associated with the user. Includes the primary.
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.
primaryWeb3WalletId	string \| null	The unique identifier for the Web3Wallet that the user signed up with.
web3Wallets	web3Wallets[]	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, thus if only the verified should be displayed, one needs to filter by `externalAccount.verification.status == 'verified'`. The `User` object also offers 2 getters that perform this filtering: `verifiedExternalAccounts` & `unverifiedAccounts`.
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 app
backupCodeEnabled	boolean	Whether the user has enabled Backup codes.
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. 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

createEmailAddress(params)

createEmailAddress(params: CreateEmailAddressParams) => Promise<EmailAddressResource>Adds an email address for the user. A new EmailAddress will be created and associated with the user.

Parameters

Name	Type	Description
email	string	The email address to associate with the user.

createPhoneNumber(params)

createPhoneNumber(phoneNumber: CreatePhoneNumberParams) => Promise<PhoneNumberResource>

Adds a phone number for the user. A new PhoneNumber will be created and associated with the user.

Parameters

This method accepts a CreatePhoneNumberParams params object:

Name	Type	Description
phoneNumber	string	The phone number to associate with the user.

Returns

Type	Description
Promise<PhoneNumberResource>	This method returns a Promise which resolves with a PhoneNumber object

createExternalAccount(params)

createExternalAccount: (params: CreateExternalAccountParams) => Promise<ExternalAccountResource>Adds an external account for the user. A new ExternalAccount will be created and associated with the user.

Parameters

This method accepts an object with two keys:

Name	Type	Description
strategy	string	The strategy corresponding to the oauth provider, e.g. `oauth_facebook`, `oauth_github`, etc
redirectUrl	string	The URL to redirect back to one the oauth flow has completed successfully or unsuccessfully.
additionalScopes	string[]	Any additional scopes you would like your user to be prompted to approve

Returns

Name	Type	Description
Promise<ExternalAccountResource>	string	This method returns a Promise which resolves with an `ExternalAccount` object

The initial state of the returned ExternalAccount will be unverified. To initiate the connection with the external provider one should redirect to the externalAccount.verification.externalVerificationRedirectURL contained in the result of createExternalAccount.

Upon return, one can inspect within the user.externalAccounts the entry that corresponds to the requested strategy:

If the connection was successful then externalAccount.verification.status should be verified
If the connection was not successful, then the externalAccount.verification.status will not be verified and the externalAccount.verification.error will contain the error encountered so that you can present corresponding feedback to the user

getSessions()

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.

Parameters

This method accepts no parameters:

Returns

Type	Description
Promise<SessionWithActivities[]>	This method returns a `Promise` which resolves to an array of SessionWithActivities objects.

setProfileImage(params)

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.

Parameters

This method accepts a SetProfileImageParams params object:

Name	Type	Description
file	Blob \| File \| null	A file or file-like object (raw data). Should be an image. Passing `null` will delete the user's current image.

Returns

Type	Description
Promise<ImageResource>	Returns a `Promise` that resolves to an <ImageResource> object.

update(params)

update(params: UpdateUserParams) => Promise<UserResource>

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

Parameters

Name	Type	Description
params	UpdateUserParams	User profile related attributes.

Returns

Type	Description
boolean	This method returns true when the user has enabled 2-factor authentication, false otherwise.

get verifiedExternalAccounts(): ExternalAccountResource[]

This getter is a convenience method for filtering all ExternalAccounts of a user that are in state verified.

createTOTP()

createTOTP() = async () => Promise<TOTPResource>

Generates a TOTP secret for a user that can be used to register the application on the user's authenticator app of choice. Note that if this method is called again (while still unverified), it replaces the previously generated secret.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<TOTPResource>	This method returns a promise that resolves to a TOTPResource

verifyTOTP(params)

verifyTOTP = async ({ code }: VerifyTOTPParams): Promise<TOTPResource>

Verifies a TOTP secret after a user has created it. The user must provide a code from their authenticator app, that has been generated using the previously created secret. This way correct setup and ownership of the authenticator app can be validated.

Parameters

Name	Type	Description
code	string	A 6 digit TOTP generated from the user's authenticator app

Returns

Type	Description
Promise<TOTPResource>	This method returns a promise that resolves to a TOTPResource

disableTOTP()

disableTOTP = async (): Promise<DeletedObjectResource>

Disables TOTP by deleting the user's TOTP secret.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<DeletedObjectResource>	This method returns a promise that resolves to a DeletedObjectResource

createBackupCode()

createBackupCode() = async () => Promise<BackupCodeResource>

Generates a fresh new set of backup codes for the user. Note that if this method is called again, it replaces the previously generated codes.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<TOTPResource>	This method returns a promise that resolves to a TOTPResource

Interfaces

ExternalAccount

Name	Type	Description
id	string	A unique identifier for this external account.
provider	OAuthProvider	The name of the OAuth provider.
externalId	string	The user's unique identifier at the OAuth provider.
emailAddress	string	A list of OAuth scopes as returned by the OAuth provider.
firstName	string	The user's first name as registered with the OAuth provider.
lastName	string	The user's last name as registered with the OAuth provider.
picture	string	URL for the user's profile picture (avatar) that's registered with the OAuth provider.
username	string \| null	The user's username as registered with the OAuth provider.
publicMetadata	{[string]: any}	Additional, opaque metadata returned by the provider during an OAuth flow.
label	string \| null	A label to differentiate external accounts of the same user and the same provider
verification	VerificationResource \| null	A Verification object tracking the verification status of the external account.

ImageResource

Name	Type	Description
id	string	A unique identifier for this image.
name	string	A name for this image. The image title.
publicUrl	string	The URL which can be used to access this image.

TOTPResource

Name	Type	Description
id	string	A unique identifier for this TOTP secret
secret	string	The generated TOTP secret. Note: this is only returned to the client upon creation and cannot be retrieved afterwards.
uri	string	A complete TOTP configuration URI including the Issuer, Account, etc that can be pasted to an authenticator app or encoded to a QR code and scanned for convenience. Just like the secret, the URI is exposed to the client only upon creation and cannot be retrieved afterwards.
verified	boolean	Whether this TOTP secret has been verified by the user by providing one code generated with it. TOTP is not enabled on the user unless they have a verified secret.
backupCodes	string[]	A set of fresh generated Backup codes. Note that this will be populated if the feature is enabled in your instance and the user doesn't already have backup codes generated.
createdAt	date	Creation date of the TOTP secret
updatedAt	date	Update timestamp of the TOTP secret

BackupCodeResource

Name	Type	Description
id	string	A unique identifier for this TOTP secret
codes	string[]	The generated set of backup codes.
createdAt	date	Creation date of the TOTP secret
updatedAt	date	Update timestamp of the TOTP secret

UpdateUserParams

Name	Type	Description
username	string	The username for the user.
firstName	string	The user's first name.
lastName	string	The user's last name.
primaryEmailAddressId	string	Use this attribute to reference an EmailAddress object by ID and associate it with the user.
primaryPhoneNumberId	string	Use this attribute to reference a PhoneNumber object by ID and associate it with the user.
password	string	The user's password.
unsafeMetadata	{[string]: any}	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.

Types

OAuthProvider

Value	Description
oauth_facebook	Specify Facebook as the verification OAuth provider.
oauth_github	Specify Github as the verification OAuth provider.
oauth_google	Specify Google as the verification OAuth provider.
oauth_hubspot	Specify HubSpot as the verification OAuth provider.
oauth_tiktok	Specify TikTok as the verification OAuth provider.
oauth_gitlab	Specify GitLab as the verification OAuth provider.
oauth_discord	Specify Discord as the verification OAuth provider.
oauth_twitter	Specify Twitter as the verification OAuth provider.
oauth_twitch	Specify Twitch as the verification OAuth provider.
oauth_linkedin	Specify LinkedIn as the verification OAuth provider.
oauth_dropbox	Specify Dropbox as the verification OAuth provider.
oauth_bitbucket	Specify Bitbucket as the verification OAuth provider.
oauth_microsoft	Specify Microsoft as the verification OAuth provider.
oauth_notion	Specify Notion as the verification OAuth provider.