Skip to main content

User object

The User object holds all of the information for a single user of your application and provides a set of methods to manage their account. Each User has at least one authentication identifier, which might be their email address, phone number, or a username.

A user can be contacted at their primary email address or primary phone number. They can have more than one registered email address or phone number, but only one of them will be their primary email address (User.primaryEmailAddress) or primary phone number (User.primaryPhoneNumber). At the same time, a user can also have one or more external accounts by connecting to social providers such as Google, Apple, Facebook, and many more (User.externalAccounts).

Finally, a User object holds profile data like the user's name, profile picture, and a set of metadata that can be used internally to store arbitrary information. The metadata are split into publicMetadata and privateMetadata. Both types are set from the Backend API, but public metadata can also be accessed from the Frontend API.

Example

The following example demonstrates how to use the useUser() hook to access the User object, which contains the current user's data such as their ID.

src/routes/page.tsx
import { useUser } from '@clerk/chrome-extension'

export default function Example() {
  const { isSignedIn, user, isLoaded } = useUser()

  // Handle loading state
  if (!isLoaded) return <div>Loading...</div>

  // Protect the page from unauthenticated users
  if (!isSignedIn) return <div>Sign in to view this page</div>

  return <div>Hello {user.id}!</div>
}

Properties

  • Name
    backupCodeEnabled
    Type
    boolean
    Description

    Indicates whether the user has enabled backup codes.

  • Name
    createdAt
    Type
    null | Date
    Description

    The date and time when the user was created.

  • Name
    createOrganizationEnabled
    Type
    boolean
    Description

    Indicates whether the user can create organizations.

  • Name
    createOrganizationsLimit
    Type
    null | number
    Description

    The maximum number of organizations the user can create.

  • Name
    deleteSelfEnabled
    Type
    boolean
    Description

    Indicates whether the user can delete their own account.

  • Name
    emailAddresses
    Type
    EmailAddressResource[]
    Description

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

  • Name
    enterpriseAccounts
    Type
    EnterpriseAccountResource[]
    Description

    An array of all the EnterpriseAccount objects associated with the user via enterprise SSO.

  • Name
    externalAccounts
    Type
    ExternalAccountResource[]
    Description

    An array of all the ExternalAccount objects associated with the user via OAuth.

  • Name
    externalId
    Type
    null | string
    Description

    The user's ID as used in your external systems. Must be unique across your instance.

  • Name
    firstName
    Type
    null | string
    Description

    The user's first name.

  • Name
    fullName
    Type
    null | string
    Description

    The user's full name.

  • Name
    hasImage
    Type
    boolean
    Description

    Indicates whether the user has uploaded an image or one was copied from OAuth. Returns false if Clerk is displaying an avatar for the user.

  • Name
    id
    Type
    string
    Description

    The unique identifier of the user.

  • Name
    imageUrl
    Type
    string
    Description

    Holds the default avatar or user's uploaded profile image. Compatible with Clerk's Image Optimization.

  • Name
    lastName
    Type
    null | string
    Description

    The user's last name.

  • Name
    lastSignInAt
    Type
    null | Date
    Description

    The date and time when the user last signed in.

  • Name
    legalAcceptedAt
    Type
    null | Date
    Description

    The date and time when the user accepted the legal compliance documents. null if Require express consent to legal documents is not enabled.

  • Name
    organizationMemberships
    Type
    OrganizationMembershipResource[]
    Description

    An array of all the OrganizationMembership objects associated with the user.

  • Name
    passkeys
    Type
    PasskeyResource[]
    Description

    An array of all the Passkey objects associated with the user.

  • Name
    passwordEnabled
    Type
    boolean
    Description

    Indicates whether the user has a password on their account.

  • Name
    phoneNumbers
    Type
    PhoneNumberResource[]
    Description

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

  • Name
    primaryEmailAddress
    Type
    null | EmailAddressResource
    Description

    The user's primary email address.

  • Name
    primaryEmailAddressId
    Type
    null | string
    Description

    The ID of the user's primary email address.

  • Name
    primaryPhoneNumber
    Type
    null | PhoneNumberResource
    Description

    The user's primary phone number.

  • Name
    primaryPhoneNumberId
    Type
    null | string
    Description

    The ID of the user's primary phone number.

  • Name
    primaryWeb3Wallet
    Type
    null | Web3WalletResource
    Description

    The user's primary Web3 wallet.

  • Name
    primaryWeb3WalletId
    Type
    null | string
    Description

    The ID of the user's primary Web3 wallet.

  • Name
    publicMetadata
    Type
    UserPublicMetadata
    Description

    Metadata that can be read from the Frontend API and Backend API and can be set only from the Backend API.

  • Name
    totpEnabled
    Type
    boolean
    Description

    Indicates whether the user has enabled TOTP.

  • Name
    twoFactorEnabled
    Type
    boolean
    Description

    Indicates whether the user has enabled two-factor authentication.

  • Name
    unsafeMetadata
    Type
    UserUnsafeMetadata
    Description

    Metadata that can be read and set from the Frontend API. It's considered unsafe because it can be modified from the frontend. 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.

  • Name
    updatedAt
    Type
    null | Date
    Description

    The date and time when the user was last updated.

  • Name
    username
    Type
    null | string
    Description

    The user's username.

  • Name
    web3Wallets
    Type
    Web3WalletResource[]
    Description

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

Methods

createBackupCode()

Generates a fresh new set of backup codes for the user. Every time the method is called, it will replace the previously generated backup codes.

Returns a BackupCodeResource object.

function createBackupCode(): Promise<BackupCodeResource>

createEmailAddress()

Adds an email address for the user. A new EmailAddress will be created and associated with the user.

Warning

Email must be enabled in your app's settings in the Clerk Dashboard.

function createEmailAddress(params: CreateEmailAddressParams): Promise<EmailAddressResource>

CreateEmailAddressParams

  • Name
    email
    Type
    string
    Description

    The email address to add to the user.

createExternalAccount()

Adds an external account for the user. A new ExternalAccount will be created and associated with the user. This method is useful if you want to allow an already signed-in user to connect their account with an external provider, such as Facebook, GitHub, etc., so that they can sign in with that provider in the future.

Warning

The social provider that you want to connect to must be enabled in your app's settings in the Clerk Dashboard.

function createExternalAccount(params: CreateExternalAccountParams): Promise<ExternalAccountResource>

CreateExternalAccountParams

  • Name
    additionalScopes?
    Type
    OAuthScope[]
    Description

    Additional scopes for your user to be prompted to approve.

  • Name
    enterpriseConnectionId?
    Type
    string
    Description

    The ID of the enterprise connection to connect to the user.

  • Name
    oidcLoginHint?
    Type
    string
    Description

    The value to pass to the OIDC login_hint parameter in the generated OAuth redirect URL.

  • Name
    oidcPrompt?
    Type
    string
    Description

    The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.

  • Name
    redirectUrl?
    Type
    string
    Description

    The full URL or path that the OAuth provider should redirect to, on successful authorization on their part. Typically, this will be a simple /sso-callback route that calls Clerk.handleRedirectCallback or mounts the <AuthenticateWithRedirectCallback /> component. See the custom flow for implementation details.

  • Name
    strategy?
    Type
    OAuthStrategy
    Description

    The strategy corresponding to the OAuth provider. For example: 'oauth_google'.

createPasskey()

Creates a passkey for the signed-in user. For an example, see the custom flow guide.

Returns a PasskeyResource object.

Note

When creating a passkey for a user in a multi-domain Clerk app, createPasskey() must be called from the primary domain.

function createPasskey(): Promise<PasskeyResource>

createPhoneNumber()

Adds a phone number for the user. A new PhoneNumber will be created and associated with the user.

Warning

Phone must be enabled in your app's settings in the Clerk Dashboard.

function createPhoneNumber(params: CreatePhoneNumberParams): Promise<PhoneNumberResource>

CreatePhoneNumberParams

  • Name
    phoneNumber
    Type
    string
    Description

    The phone number to add to the user.

createTOTP()

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

Returns a TOTPResource object.

Warning

The Authenticator application multi-factor strategy must be enabled in your app's settings in the Clerk Dashboard. See the Multi-factor authentication section to learn more.

function createTOTP(): Promise<TOTPResource>

createWeb3Wallet()

Adds a Web3 wallet for the user. A new Web3WalletResource will be created and associated with the user.

function createWeb3Wallet(params: CreateWeb3WalletParams): Promise<Web3WalletResource>

CreateWeb3WalletParams

  • Name
    web3Wallet
    Type
    string
    Description

    The Web3 wallet address, made up of either 0x + 40 hexadecimal characters or a base58 encoded ed25519 public key (for Solana wallets).

delete()

Deletes the current user.

function delete(): Promise<void>

disableTOTP()

Disables TOTP by deleting the user's TOTP secret.

Returns a DeletedObjectResource object.

Warning

The Authenticator application multi-factor strategy must be enabled in your app's settings in the Clerk Dashboard. See the Multi-factor authentication section to learn more.

function disableTOTP(): Promise<DeletedObjectResource>

getOrganizationCreationDefaults()

Gets organization creation defaults for the current user.

Returns a OrganizationCreationDefaultsResource object.

function getOrganizationCreationDefaults(): Promise<OrganizationCreationDefaultsResource>

getOrganizationInvitations()

Gets a list of Organization invitations for the user.

Returns a ClerkPaginatedResponse of UserOrganizationInvitation objects.

function getOrganizationInvitations(params?: GetUserOrganizationInvitationsParams): Promise<ClerkPaginatedResponse<UserOrganizationInvitationResource>>

GetUserOrganizationInvitationsParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.

  • Name
    pageSize?
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page. Defaults to 10.

  • Name
    status?
    Type
    "pending" | "accepted" | "revoked" | "expired"
    Description

    The status an invitation can have.

getOrganizationMemberships()

Gets a list of Organization memberships for the user. Returns a ClerkPaginatedResponse of OrganizationMembershipResource objects.

function getOrganizationMemberships(
  params?: GetUserOrganizationMembershipParams,
): Promise<ClerkPaginatedResponse<OrganizationMembershipResource>>

GetUserOrganizationMembershipParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

getOrganizationSuggestions()

Gets a list of Organization suggestions for the user.

Returns a ClerkPaginatedResponse of OrganizationSuggestionResource objects.

function getOrganizationSuggestions(params?: GetUserOrganizationSuggestionsParams): Promise<ClerkPaginatedResponse<OrganizationSuggestionResource>>

GetUserOrganizationSuggestionsParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.

  • Name
    pageSize?
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page. Defaults to 10.

  • Name
    status?
    Type
    "pending" | "accepted" | ("pending" | "accepted")[]
    Description

    The status a suggestion can have.

getPaymentMethods()

Gets a list of payment methods that have been stored.

Returns a ClerkPaginatedResponse of BillingPaymentMethodResource objects.

function getPaymentMethods(params?: GetPaymentMethodsParams): Promise<ClerkPaginatedResponse<BillingPaymentMethodResource>>

GetPaymentMethodsParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that specifies which page to fetch. For example, if initialPage is set to 10, it will skip the first 9 pages and fetch the 10th page. Defaults to 1.

  • Name
    pageSize?
    Type
    number
    Description

    A number that specifies the maximum number of results to return per page. Defaults to 10.

getSessions()

Gets all active sessions for this user. This method uses a cache so a network request will only be triggered only once.

Returns an array of SessionWithActivities objects.

function getSessions(): Promise<SessionWithActivitiesResource[]>

initializePaymentMethod()

Initializes a payment method.

Returns a BillingInitializedPaymentMethodResource object.

function initializePaymentMethod(params: InitializePaymentMethodParams): Promise<BillingInitializedPaymentMethodResource>

InitializePaymentMethodParams

  • Name
    gateway
    Type
    "stripe"
    Description

    The payment gateway to use.

isPrimaryIdentification()

A check whether or not the given resource is the primary identifier for the user.

function isPrimaryIdentification(ident: Web3WalletResource | EmailAddressResource | PhoneNumberResource): boolean

Parameters

leaveOrganization()

Leaves an organization that the user is a member of.

Returns a DeletedObjectResource object.

function leaveOrganization(organizationId: string): Promise<DeletedObjectResource>

Parameters

  • Name
    organizationId
    Type
    string
    Description

    The ID of the organization to leave.

reload()

Reloads the resource, which is useful when you want to access the latest user data after performing a mutation. To make the updated data immediately available, this method forces a session token refresh instead of waiting for the automatic refresh cycle that could temporarily retain stale information. Learn more about forcing a token refresh.

function reload(p?: ClerkResourceReloadParams): Promise<UserResource>

ClerkResourceReloadParams

  • Name
    rotatingTokenNonce?
    Type
    string
    Description

    A nonce to use for rotating the user's token. Used in native application OAuth flows to allow the native client to update its JWT once despite changes in its rotating token.

You only need to call user.reload() if you've updated the User object outside of the user.update() method or Clerk hooks; for example, if you made changes through an API endpoint.

removePassword()

Removes the user's password.

function removePassword(params: RemoveUserPasswordParams): Promise<UserResource>

RemoveUserPasswordParams

  • Name
    currentPassword?
    Type
    string
    Description

    The user's current password.

setProfileImage()

Adds the user's profile image or replaces it if one already exists. This method will upload an image and associate it with the user.

function setProfileImage(params: SetProfileImageParams): Promise<ImageResource>

SetProfileImageParams

  • Name
    file
    Type
    Blob | File | string | null
    Description

    The file to set as the user's profile image, or null to remove the current image.

update()

Updates the user's attributes. Use this method to save information you collected about the user.

The appropriate settings must be enabled in the Clerk Dashboard for the user to be able to update their attributes. For example, if you want to use the update({ firstName }) method, you must enable the First and last name setting. It can be found on the User & authentication page in the Clerk Dashboard.

function update(params: UpdateUserParams): Promise<UserResource>

UpdateUserParams

  • Name
    firstName?
    Type
    string
    Description

    The user's first name.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name.

  • Name
    primaryEmailAddressId?
    Type
    string
    Description

    The ID for the EmailAddress that the user has set as primary.

  • Name
    primaryPhoneNumberId?
    Type
    string
    Description

    The ID for the PhoneNumber that the user has set as primary.

  • Name
    primaryWeb3WalletId?
    Type
    string
    Description

    The ID for the Web3Wallet that the user signed up with.

  • Name
    unsafeMetadata?
    Type
    UserUnsafeMetadata
    Description

    Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the User object. Using update() to update this value fully replaces the existing value. To perform a merge, use updateMetadata() instead.

  • Name
    username?
    Type
    string
    Description

    The user's username. Only supported if username is enabled in the instance settings.

updateMetadata()

Updates the user's unsafeMetadata using deep-merge semantics. Unlike update(), which fully replaces unsafeMetadata, this method merges the provided value with the existing unsafeMetadata. Top-level and nested keys are merged, and any key set to null is removed. Only unsafeMetadata is writable from the frontend; publicMetadata and privateMetadata can only be set from the Backend API.

function updateMetadata(params: UpdateUserMetadataParams): Promise<UserResource>

UpdateUserMetadataParams

  • Name
    unsafeMetadata
    Type
    UserUnsafeMetadata
    Description

    The metadata to deep-merge with the user's existing unsafeMetadata. Keys at any nesting level whose value is null are removed.

updatePassword()

Updates the user's password.

function updatePassword(params: UpdateUserPasswordParams): Promise<UserResource>

UpdateUserPasswordParams

  • Name
    currentPassword?
    Type
    string
    Description

    The user's current password.

  • Name
    newPassword
    Type
    string
    Description

    The user's new password.

  • Name
    signOutOfOtherSessions?
    Type
    boolean
    Description

    Whether to sign out the user from all their active sessions once their password is updated.

verifyTOTP()

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 set up and ownership of the authenticator app can be validated.

Returns a TOTPResource object.

Warning

The Authenticator application multi-factor strategy must be enabled in your app's settings in the Clerk Dashboard. See the Multi-factor authentication section to learn more.

function verifyTOTP(params: VerifyTOTPParams): Promise<TOTPResource>

VerifyTOTPParams

  • Name
    code
    Type
    string
    Description

    The code to verify.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub