Skip to main content
Docs

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.

app/(user)/index.tsx
import { useUser } from '@clerk/expo'
import { Text, View } from 'react-native'

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

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

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

  return (
    <View>
      <Text>Hello {user.id}!</Text>
    </View>
  )
}

Properties

  • Name
    backupCodeEnabled
    Type
    boolean
    Description

    Indicates whether the user has enabled backup codes for their account.

  • Name
    createdAt
    Type
    Date | null
    Description

    The date when the user was first created.

  • Name
    createOrganizationEnabled
    Type
    boolean
    Description

    Indicates whether the Organization creation permission is enabled for the user. Defaults to false.

  • Name
    createOrganizationsLimit
    Type
    number | null
    Description

    The number of Organizations that the user can create, or null if not set. If the value is 0, the user can create unlimited Organizations.

  • Name
    deleteSelfEnabled
    Type
    boolean
    Description

    Indicates whether the user is able to delete their own account.

  • Name
    emailAddresses
    Type
    EmailAddress[]
    Description

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

  • Name
    enterpriseAccounts
    Type
    EnterpriseAccount[]
    Description

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

  • Name
    externalAccounts
    Type
    ExternalAccount[]
    Description

    An array of all the ExternalAccount objects associated with the user via OAuth. This includes both verified & unverified external accounts.

  • Name
    externalId
    Type
    string | null
    Description

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

  • Name
    firstName
    Type
    string | null
    Description

    The user's first name.

  • Name
    fullName
    Type
    string | null
    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
    hasVerifiedEmailAddress
    Type
    boolean
    Description

    Indicates whether the user has verified an email address.

  • Name
    hasVerifiedPhoneNumber
    Type
    boolean
    Description

    Indicates whether the user has verified a phone number.

  • Name
    id
    Type
    string
    Description

    The user's unique identifier.

  • Name
    imageUrl
    Type
    string
    Description

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

  • Name
    lastSignInAt
    Type
    Date | null
    Description

    The date when the user last signed in. null if the user has never signed in.

  • Name
    lastName
    Type
    string | null
    Description

    The user's last name.

  • Name
    legalAcceptedAt
    Type
    Date | null
    Description

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

  • Name
    organizationMemberships
    Type
    OrganizationMembership[]
    Description

    A list of OrganizationMemberships representing the list of Organizations the user is a member of.

  • Name
    passkeys
    Type
    PasskeyResource[] | null
    Description

    An array of passkeys associated with the user's account.

  • Name
    passwordEnabled
    Type
    boolean
    Description

    Indicates whether the user has a password on their account.

  • Name
    phoneNumbers
    Type
    PhoneNumber[]
    Description

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

  • Name
    primaryEmailAddress
    Type
    EmailAddress | null
    Description

    Information about the user's primary email address.

  • Name
    primaryEmailAddressId
    Type
    string | null
    Description

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

  • Name
    primaryPhoneNumber
    Type
    PhoneNumber | null
    Description

    Information about the user's primary phone number.

  • Name
    primaryPhoneNumberId
    Type
    string | null
    Description

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

  • Name
    primaryWeb3Wallet
    Type
    Web3Wallet | null
    Description

    The Web3Wallet that the user signed up with.

  • Name
    primaryWeb3WalletId
    Type
    string | null
    Description

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

  • Name
    privateMetadata
    Type
    UserPrivateMetadata
    Description

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

  • 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 by generating a TOTP secret and verifying it via an authenticator app.

  • 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
    Date | null
    Description

    The date when the user was last updated.

  • Name
    verifiedExternalAccounts
    Type
    ExternalAccount[]
    Description

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

  • Name
    verifiedWeb3Wallets
    Type
    Web3Wallet[]
    Description

    An array of all the Web3Wallet objects associated with the user that are verified.

  • Name
    unverifiedExternalAccounts
    Type
    ExternalAccount[]
    Description

    An array of all the ExternalAccount objects associated with the user via OAuth that are not verified.

  • Name
    username
    Type
    string | null
    Description

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

  • Name
    web3Wallets
    Type
    Web3Wallet[]
    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<EmailAddress>

CreateEmailAddressParams

  • Name
    email
    Type
    string
    Description

    The email address to be added 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<ExternalAccount>

CreateExternalAccountParams

  • Name
    strategy
    Type
    OAuthStrategy
    Description

    The strategy corresponding to the OAuth provider. For example: 'oauth_facebook', 'oauth_github', etc.

  • 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
    additionalScopes?
    Type
    string[]
    Description

    Additional scopes for your user to be prompted to approve.

  • Name
    oidcPrompt?
    Type
    string
    Description

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

  • Name
    oidcLoginHint?
    Type
    string
    Description

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

createPasskey()

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

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 be added to the user. Must be in E.164 format.

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

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>

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>

getOrganizationInvitations()

Retrieves a list of Organization invitations for the user. Returns a ClerkPaginatedResponse of UserOrganizationInvitation objects.

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

GetUserOrganizationInvitationsParams

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

  • Name
    status?
    Type
    'pending' | 'accepted' | 'revoked'
    Description

    The status an invitation can have.

getOrganizationMemberships()

Retrieves 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()

Retrieves a list of Organization suggestions for the user. Returns a ClerkPaginatedResponse of OrganizationSuggestion objects.

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

GetUserOrganizationSuggestionsParams

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

  • Name
    status?
    Type
    'pending' | 'accepted' | ['pending' | 'accepted']
    Description

    The status an invitation can have.

getOrganizationCreationDefaults()

Retrieves organization creation defaults for the current user. Returns a OrganizationCreationDefaultsResource object.

function getOrganizationCreationDefaults(): Promise<OrganizationCreationDefaultsResource>

leaveOrganization()

Leaves an organization that the user is a member of. Returns a DeletedObjectResource object.

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

initializePaymentMethod()

Initializes a payment method for the user.

function initializePaymentMethod(params): Promise<BillingInitializedPaymentMethod>

addPaymentMethod()

Adds a payment method for the user.

function addPaymentMethod(params): Promise<BillingPaymentMethod>

getPaymentMethods()

Retrieves payment methods for the user.

function getPaymentMethods(params?): Promise<{
  total_count: number
  data: BillingPaymentMethod[]
}>

getSessions()

Retrieves 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<SessionWithActivities[]>

isPrimaryIdentification()

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

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

Parameters

reload()

Reloads the user's data from Clerk's API, 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.

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.

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

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.

removePassword()

Removes the user's password.

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

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.

ImageResource
  • Name
    id?
    Type
    string
    Description

    The unique identifier of the image.

  • Name
    name
    Type
    string | null
    Description

    The name of the image.

  • Name
    publicUrl
    Type
    string | null
    Description

    The publicly accessible url for the 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<User>

UpdateUserParams

  • Name
    username?
    Type
    string
    Description

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

  • 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. Updating this value overrides the previous value; it does not merge. To perform a merge, you can pass something like { …user.unsafeMetadata, …newData } to this parameter.

updatePassword()

Updates the user's password. Passwords must be at least 8 characters long.

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

UpdateUserPasswordParams

  • Name
    newPassword
    Type
    string
    Description

    The user's new password.

  • Name
    currentPassword?
    Type
    string
    Description

    The user's current password.

  • Name
    signOutOfOtherSessions?
    Type
    boolean | undefined
    Description

    If set to true, all sessions will be signed out.

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

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

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub