User - Clerk

Search…
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 addresses, 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
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, a combination of their first and last 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
​EmailAddress[]
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
​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, 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.
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
This method accepts a CreateEmailAddressParams params object:
Name
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
Returns
This method accepts a CreatePhoneNumberParams params object:
Name
Description
phoneNumber
string
The phone number to associate with the user.
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
Returns
This method accepts an object with two keys:
Name
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.
Promise<ExternalAccountResource>
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
Returns
This method accepts no parameters.
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
Returns
Name
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.
Promise<string>
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
Returns
This method accepts a SetProfileImageParams params object:
Name
Description
file
Blob | File
A file or file-like object (raw data). Should be an image.
Promise<ImageResource>
This method
twoFactorEnabled()
twoFactorEnabled() => boolean
Checks if the user has enabled 2-step verification (2FA) for their account.
Parameters
Returns
This method accepts no parameters.
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
Returns
Name
Description
params
​UpdateUserParams​
User profile related attributes.
Promise<UserResource>
This method returns a Promise which resolves to a User object.
​
get verifiedExternalAccounts(): ExternalAccountResource[]
This getter is a convenience method for filtering all ExternalAccounts of a user that are in state verified.
get verifiedExternalAccounts(): ExternalAccountResource[]
This getter is a convenience method for filtering all ExternalAccounts of a user that are not in state verified.
Interfaces
ExternalAccount
Property
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
The user's email address registered with the OAuth provider.
approvedScopes
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 first 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
Property
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
Property
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} | 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.
GetUserTokenOptions
Property
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
facebook | github | google | hubspot | tiktok | gitlab | discord | twitter | twitch | linkedin | dropbox | bitbucket | microsoft | notion
Value
Description
facebook
Facebook OAuth provider.
github
Github OAuth provider.
google
Google OAuth provider.
hubspot
Hubspot OAuth provider.
tiktok
TikTok OAuth provider.
gitlab
GitLab OAuth provider.
discord
Discord OAuth provider.
twitter
Twitter OAuth provider.
twitch
Twitch OAuth provider.
linkedin
LinkedIn OAuth provider.
dropbox
Dropbox OAuth provider.
bitbucket
Bitbucket OAuth provider.
microsoft
Microsoft OAuth provider.
notion
Notion OAuth provider.
SignUp
OrganizationInvitation
Last modified 1mo ago