Overview

The User object models a user's account information.

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.
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: ({ strategy, redirect_url }: { strategy: OAuthStrategy; redirect_url?: string; }) => 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
redirect_url	string	The URL to redirect back to one the oauth flow has completed successfully or unsuccessfully.

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.

getToken(service, options?)

getToken(service: JWTService, options?: GetUserTokenOptions) => Promise<string>Retrieves the user's token for the given integration service. This method uses a cache so a network request will only be made if the token in memory has expired. The TTL for each token is one minute.

Parameters

Name	Type	Description
service	JWTService	The name of the service that you've integrated with.
options?	GetUserTokenOptions	Optionally pass the leeway for expiring the cache. Default leeway is 10 seconds and cannot exceed the token TTL, which is 1 minute.

Returns

Type	Description
Promise<SessionWithActivities[]>	Returns a `Promise` that resolves to a string. The string is the user's token for the provided integration service.

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	A file or file-like object (raw data). Should be an image.

Returns

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

twoFactorEnabled()

twoFactorEnabled() => booleanChecks if the user has enabled 2-step verification (2FA) for their account.

Parameters

This method accepts no parameters.

Returns

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

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.

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.

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.

GetUserTokenOptions

Name	Type	Description
leewayInSeconds?	number	The number of seconds that we allow the token to be cached.

Types

JWTService

clerk | firebase | hasura

Value	Description
clerk	Get a short-lived Clerk JWT.
firebase	Integration with Firebase.
hasura	Integration with Hasura.

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.