Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

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

totpEnabledboolean

Whether the user has enabled TOTP by generating a TOTP secret and verifying it via an authenticator app

backupCodeEnabledboolean

Whether the user has enabled Backup codes.

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.

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 | null

A file or file-like object (raw data). Should be an image. Passing `null` will delete the user's current image.


Returns

TypeDescription
Promise<ImageResource>

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

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.

createTOTP()

createTOTP() = async () => Promise<TOTPResource>

Generates a TOTP secret for a user that can be used to register the application on the user's authenticator app of choice. Note that if this method is called again (while still unverified), it replaces the previously generated secret.

Parameters

This method accepts no parameters.

Returns

TypeDescription
Promise<TOTPResource>

This method returns a promise that resolves to a TOTPResource

verifyTOTP(params)

verifyTOTP = async ({ code }: VerifyTOTPParams): Promise<TOTPResource>

Verifies a TOTP secret after a user has created it. The user must provide a code from their authenticator app, that has been generated using the previously created secret. This way correct setup and ownership of the authenticator app can be validated.

Parameters

NameTypeDescription
codestring

A 6 digit TOTP generated from the user's authenticator app

Returns

TypeDescription
Promise<TOTPResource>

This method returns a promise that resolves to a TOTPResource

disableTOTP()

disableTOTP = async (): Promise<DeletedObjectResource>

Disables TOTP by deleting the user's TOTP secret.

Parameters

This method accepts no parameters.

Returns

TypeDescription
Promise<DeletedObjectResource>

This method returns a promise that resolves to a DeletedObjectResource

createBackupCode()

createBackupCode() = async () => Promise<BackupCodeResource>

Generates a fresh new set of backup codes for the user. Note that if this method is called again, it replaces the previously generated codes.

Parameters

This method accepts no parameters.

Returns

TypeDescription
Promise<TOTPResource>

This method returns a promise that resolves to a TOTPResource

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.

TOTPResource

NameTypeDescription
idstring

A unique identifier for this TOTP secret

secretstring

The generated TOTP secret. Note: this is only returned to the client upon creation and cannot be retrieved afterwards.

uristring

A complete TOTP configuration URI including the Issuer, Account, etc that can be pasted to an authenticator app or encoded to a QR code and scanned for convenience. Just like the secret, the URI is exposed to the client only upon creation and cannot be retrieved afterwards.

verifiedboolean

Whether this TOTP secret has been verified by the user by providing one code generated with it. TOTP is not enabled on the user unless they have a verified secret.

backupCodesstring[]

A set of fresh generated Backup codes. Note that this will be populated if the feature is enabled in your instance and the user doesn't already have backup codes generated.

createdAtdate

Creation date of the TOTP secret

updatedAtdate

Update timestamp of the TOTP secret

BackupCodeResource

NameTypeDescription
idstring

A unique identifier for this TOTP secret

codesstring[]

The generated set of backup codes.

createdAtdate

Creation date of the TOTP secret

updatedAtdate

Update timestamp of the TOTP secret

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.

Types

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