Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

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

NameTypeDescription
idstring

A unique identifier for the user.

firstNamestring | null

The user's first name.

lastNamestring

The user's last name.

fullNamestring | null

The user's full name

usernamestring | null

The user's username.

profileImageUrlstring | null

The URL for the user's profile image.

primaryEmailAddressEmailAddress | null

Information about the user's primary email address.

primaryEmailAddressIdstring | null

The unique identifier for the EmailAddress that the user has set as primary.

emailAddressesemailAddresses[]

Any array of all the EmailAddress objects associated with the user. Includes the primary.

primaryPhoneNumberPhoneNumber[] | null

Information about the user's primary phone number.

primaryPhoneNumberIdstring | null

The unique identifier for the PhoneNumber that the user has set as primary.

phoneNumbersPhoneNumber[]

Any array of all the PhoneNumber objects associated with the user. Includes the primary.

primaryWeb3WalletIdstring | null

The unique identifier for the Web3Wallet that the user signed up with.

web3Walletsweb3Wallets[]

Any array of all the Web3Wallet objects associated with the user. Includes the primary.

externalAccountsExternalAccount[]

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.

passwordEnabledboolean

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.

lastSignInAtDate

Date when the user last signed in.
May be empty if the user has never signed in.

createdAtDate

Date when the user was first created.

updatedAtDate

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

NameTypeDescription
emailstring

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:

NameTypeDescription
phoneNumberstring

The phone number to associate with the user.

Returns

TypeDescription
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:

NameTypeDescription
strategystring

The strategy corresponding to the oauth provider, e.g. oauth_facebook, oauth_github, etc

redirect_urlstring

The URL to redirect back to one the oauth flow has completed successfully or unsuccessfully.

Returns

NameTypeDescription
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

TypeDescription
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

NameTypeDescription
serviceJWTService

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

TypeDescription
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:

NameTypeDescription
fileBlob | File

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


Returns

TypeDescription
Promise<ImageResource>

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

twoFactorEnabled()

twoFactorEnabled() => boolean

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

Parameters

This method accepts no parameters.

Returns

TypeDescription
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

NameTypeDescription
paramsUpdateUserParams

User profile related attributes.

Returns

TypeDescription
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

NameTypeDescription
idstring

A unique identifier for this external account.

providerOAuthProvider

The name of the OAuth provider.

externalIdstring

The user's unique identifier at the OAuth provider.

emailAddressstring

A list of OAuth scopes as returned by the OAuth provider.

firstNamestring

The user's first name as registered with the OAuth provider.

lastNamestring

The user's last name as registered with the OAuth provider.

picturestring

URL for the user's profile picture (avatar) that's registered with the OAuth provider.

usernamestring | 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.

labelstring | null

A label to differentiate external accounts of the same user and the same provider

verificationVerificationResource | null

A Verification object tracking the verification status of the external account.

ImageResource

NameTypeDescription
idstring

A unique identifier for this image.

namestring

A name for this image. The image title.

publicUrlstring

The URL which can be used to access this image.

UpdateUserParams

NameTypeDescription
usernamestring

The username for the user.

firstNamestring

The user's first name.

lastNamestring

The user's last name.

primaryEmailAddressIdstring

Use this attribute to reference an EmailAddress object by ID and associate it with the user.

primaryPhoneNumberIdstring

Use this attribute to reference a PhoneNumber object by ID and associate it with the user.

passwordstring

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

NameTypeDescription
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
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.

Was this helpful?

Clerk © 2022