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.
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
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
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
Any array of all the Web3Wallet objects associated with the user. Includes the primary.
externalAccounts
Any array of all the ExternalAccount objects associated with the user with OAuth.
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.
createdAt
Date
Date when the user was first created.
updatedAt
Date
Date of the last time the user was updated.

Methods

createEmailAddress(email)

createEmailAddress(email: string) => Promise<EmailAddressResource>
Adds an email address for the user. A new EmailAddress will be created and associated with the user.
Parameters
Returns
Name
Description
email
string
The email address to associate with the user.
This method returns a Promise which resolves with an EmailAddress object.

createPhoneNumber(phoneNumber)

createPhoneNumber(phoneNumber: string) => Promise<PhoneNumberResource>
Adds a phone number for the user. A new PhoneNumber will be created and associated with the user.
Parameters
Returns
Name
Description
phoneNumber
string
The phone number to associate with the user.
This method returns a Promise which resolves with a PhoneNumber object

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.
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
The name of the service that you've integrated with.
options?
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(file)

setProfileImage(file: Blob | File) => 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
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
User profile related attributes.
Promise<UserResource>
This method returns a Promise which resolves to a User object.

Interfaces

ExternalAccount

Property
Description
id
string
A unique identifier for this external account.
provider
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.

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
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.
Last modified 6d ago