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

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.

externalAccounts

ExternalAccount[]

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
Parameters

Name

Description

email

string

The email address to associate with the user.

Returns

Promise<EmailAddressResource>

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
Parameters

Name

Description

phoneNumber

string

The phone number to associate with the user.

Returns

Promise<PhoneNumberResource>

This method returns a Promise which resolves with a PhoneNumber object.

delete()

delete() => Promise<void>

Deletes the user.

Parameters
Returns
Parameters

This method accepts no parameters.

Returns

Promise<void>

This method returns a Promise which doesn't resolve to any value.

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
Parameters

This method accepts no parameters.

Returns

Promise<SessionWithActivities[]>

This method returns a Promise which resolves to an array of SessionWithActivities objects.

getToken(service, options?)

getToken(service: JWTService, options?: UserGetTokenOptions) => 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
Parameters

Name

Description

service

JWTService

The name of the service that you've integrated with.

options?

UserGetTokenOptions

Optionally pass the leeway for expiring the cache. Default leeway is 10 seconds and cannot exceed the token TTL, which is 1 minute.

Returns

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
Parameters

Name

Description

file

Blob | File

A file or file-like object (raw data). Should be an image.

Returns

Promise<ImageResource>

This method

twoFactorEnabled()

twoFactorEnabled() => boolean

Checks if the user has enabled 2-step verification (2FA) for their account.

Parameters
Returns
Parameters

This method accepts no parameters.

Returns

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
Parameters

Name

Description

params

UpdateUserParams

User profile related attributes.

Returns

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

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.

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.

UserGetTokenOptions

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

Value

Description

facebook

Facebook OAuth provider.

github

Github OAuth provider.

google

Google OAuth provider.

hubspot

Hubspot OAuth provider.

tiktok

TikTok OAuth provider.