# 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](https://clerk.com/docs/js-frontend/guides/configure/auth-strategies/social-connections/overview.md) 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](https://clerk.com/docs/guides/users/extending.md?sdk=js-frontend) 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](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}, but public metadata can also be accessed from the [Frontend API](https://clerk.com/docs/reference/frontend-api){{ target: '_blank' }}.
## Example
The `User` object is available on the [Clerk](https://clerk.com/docs/js-frontend/reference/objects/clerk.md) object.
filename: src/main.js
```js
import { Clerk } from '@clerk/clerk-js'
const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY
// Initialize Clerk with your Clerk Publishable Key
const clerk = new Clerk(publishableKey)
// Load Clerk
await clerk.load()
// Access the user object
await clerk.user
```
## Properties
| Property | Type | Description |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `backupCodeEnabled` | `boolean` | Indicates whether the user has enabled backup codes. |
| `createdAt` | `null | Date` | The date and time when the user was created. |
| `createOrganizationEnabled` | `boolean` | Indicates whether the user can create organizations. |
| `createOrganizationsLimit` | `null | number` | The maximum number of organizations the user can create. |
| `deleteSelfEnabled` | `boolean` | Indicates whether the user can delete their own account. |
| `emailAddresses` | EmailAddressResource[] | An array of all the `EmailAddress` objects associated with the user. Includes the primary. |
| `enterpriseAccounts` | EnterpriseAccountResource[] | An array of all the `EnterpriseAccount` objects associated with the user via enterprise SSO. |
| `externalAccounts` | ExternalAccountResource[] | An array of all the `ExternalAccount` objects associated with the user via OAuth. |
| `externalId` | `null | string` | The user's ID as used in your external systems. Must be unique across your instance. |
| `firstName` | `null | string` | The user's first name. |
| `fullName` | `null | string` | The user's full name. |
| `hasImage` | `boolean` | 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. |
| `id` | `string` | The unique identifier of the user. |
| `imageUrl` | `string` | Holds the default avatar or user's uploaded profile image. Compatible with Clerk's [Image Optimization](https://clerk.com/docs/guides/development/image-optimization.md?sdk=js-frontend). |
| `lastName` | `null | string` | The user's last name. |
| `lastSignInAt` | `null | Date` | The date and time when the user last signed in. |
| `legalAcceptedAt` | `null | Date` | The date and time when the user accepted the legal compliance documents. `null` if [**Require express consent to legal documents**](https://clerk.com/docs/guides/secure/legal-compliance.md?sdk=js-frontend) is not enabled. |
| `organizationMemberships` | OrganizationMembershipResource[] | An array of all the `OrganizationMembership` objects associated with the user. |
| `passkeys` | PasskeyResource[] | An array of all the `Passkey` objects associated with the user. |
| `passwordEnabled` | `boolean` | Indicates whether the user has a password on their account. |
| `phoneNumbers` | PhoneNumberResource[] | An array of all the `PhoneNumber` objects associated with the user. Includes the primary. |
| `primaryEmailAddress` | null | EmailAddressResource | The user's primary email address. |
| `primaryEmailAddressId` | `null | string` | The ID of the user's primary email address. |
| `primaryPhoneNumber` | null | PhoneNumberResource | The user's primary phone number. |
| `primaryPhoneNumberId` | `null | string` | The ID of the user's primary phone number. |
| `primaryWeb3Wallet` | null | Web3WalletResource | The user's primary Web3 wallet. |
| `primaryWeb3WalletId` | `null | string` | The ID of the user's primary Web3 wallet. |
| `publicMetadata` | [UserPublicMetadata](https://clerk.com/docs/js-frontend/reference/types/metadata.md#user-public-metadata) | Metadata that can be read from the Frontend API and Backend API and can be set only from the Backend API. |
| `totpEnabled` | `boolean` | Indicates whether the user has enabled TOTP. |
| `twoFactorEnabled` | `boolean` | Indicates whether the user has enabled two-factor authentication. |
| `unsafeMetadata` | [UserUnsafeMetadata](https://clerk.com/docs/js-frontend/reference/types/metadata.md#user-unsafe-metadata) | 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](https://clerk.com/docs/js-frontend/reference/objects/sign-up-future.md) object. The value of that field will be automatically copied to the user's unsafe metadata once the sign-up is complete. |
| `updatedAt` | `null | Date` | The date and time when the user was last updated. |
| `username` | `null | string` | The user's username. |
| `web3Wallets` | Web3WalletResource[] | 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](https://clerk.com/docs/js-frontend/reference/types/backup-code-resource.md) object.
```typescript
function createBackupCode(): Promise
```
### `createEmailAddress()`
Adds an email address for the user. A new [EmailAddress](https://clerk.com/docs/js-frontend/reference/types/email-address.md) will be created and associated with the user.
> [**Email** must be enabled](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#email) in your app's settings in the Clerk Dashboard.
```typescript
function createEmailAddress(params: CreateEmailAddressParams): Promise
```
#### `CreateEmailAddressParams`
| Property | Type | Description |
| -------------------------- | -------- | ------------------------------------- |
| `email` | `string` | The email address to add to the user. |
### `createExternalAccount()`
Adds an external account for the user. A new [ExternalAccount](https://clerk.com/docs/js-frontend/reference/types/external-account.md) 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.
> The social provider that you want to connect to [must be enabled](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#sso-connections) in your app's settings in the Clerk Dashboard.
```typescript
function createExternalAccount(params: CreateExternalAccountParams): Promise
```
#### `CreateExternalAccountParams`
| Property | Type | Description |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `additionalScopes?` | `OAuthScope[]` | Additional scopes for your user to be prompted to approve. |
| `enterpriseConnectionId?` | `string` | The ID of the enterprise connection to connect to the user. |
| `oidcLoginHint?` | `string` | The value to pass to the [OIDC `login_hint` parameter](https://openid.net/specs/openid-connect-core-1_0.html#:~:text=login_hint,in%20(if%20necessary).) in the generated OAuth redirect URL. |
| `oidcPrompt?` | `string` | The value to pass to the [OIDC `prompt` parameter](https://openid.net/specs/openid-connect-core-1_0.html#:~:text=prompt,reauthentication%20and%20consent.) in the generated OAuth redirect URL. |
| `redirectUrl?` | `string` | 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](https://clerk.com/docs/js-frontend/reference/objects/clerk.md#handle-redirect-callback) or mounts the [](https://clerk.com/docs/js-frontend/reference/components/control/authenticate-with-redirect-callback.md) component. See the [custom flow](https://clerk.com/docs/guides/development/custom-flows/authentication/oauth-connections.md?sdk=js-frontend) for implementation details. |
| `strategy?` | [OAuthStrategy](https://clerk.com/docs/js-frontend/reference/types/sso.md#o-auth-strategy) | 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](https://clerk.com/docs/guides/development/custom-flows/authentication/passkeys.md?sdk=js-frontend#create-user-passkeys).
Returns a [PasskeyResource](https://clerk.com/docs/js-frontend/reference/types/passkey-resource.md) object.
> When creating a passkey for a user in a multi-domain Clerk app, `createPasskey()` must be called from the primary domain.
```typescript
function createPasskey(): Promise
```
### `createPhoneNumber()`
Adds a phone number for the user. A new [PhoneNumber](https://clerk.com/docs/js-frontend/reference/types/phone-number.md) will be created and associated with the user.
> [**Phone** must be enabled](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#phone) in your app's settings in the Clerk Dashboard.
```typescript
function createPhoneNumber(params: CreatePhoneNumberParams): Promise
```
#### `CreatePhoneNumberParams`
| Property | Type | Description |
| -------------------------------------- | -------- | ------------------------------------ |
| `phoneNumber` | `string` | 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](https://clerk.com/docs/js-frontend/reference/types/totp-resource.md) object.
> The **Authenticator application** multi-factor strategy must be enabled in your app's settings in the Clerk Dashboard. See the [Multi-factor authentication](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#multi-factor-authentication) section to learn more.
```typescript
function createTOTP(): Promise
```
### `createWeb3Wallet()`
Adds a Web3 wallet for the user. A new [Web3WalletResource](https://clerk.com/docs/js-frontend/reference/types/web3-wallet.md) will be created and associated with the user.
```typescript
function createWeb3Wallet(params: CreateWeb3WalletParams): Promise
```
#### `CreateWeb3WalletParams`
| Property | Type | Description |
| ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `web3Wallet` | `string` | 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.
```typescript
function delete(): Promise
```
### `disableTOTP()`
Disables TOTP by deleting the user's TOTP secret.
Returns a [DeletedObjectResource](https://clerk.com/docs/js-frontend/reference/types/deleted-object-resource.md) object.
> The **Authenticator application** multi-factor strategy must be enabled in your app's settings in the Clerk Dashboard. See the [Multi-factor authentication](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#multi-factor-authentication) section to learn more.
```typescript
function disableTOTP(): Promise
```
### `getOrganizationCreationDefaults()`
Gets organization creation defaults for the current user.
Returns a [OrganizationCreationDefaultsResource](https://clerk.com/docs/js-frontend/reference/types/organization-creation-defaults.md) object.
```typescript
function getOrganizationCreationDefaults(): Promise
```
### `getOrganizationInvitations()`
Gets a list of Organization invitations for the user.
Returns a [ClerkPaginatedResponse](https://clerk.com/docs/js-frontend/reference/types/clerk-paginated-response.md) of [UserOrganizationInvitation](https://clerk.com/docs/js-frontend/reference/types/user-organization-invitation.md) objects.
```typescript
function getOrganizationInvitations(params?: GetUserOrganizationInvitationsParams): Promise>
```
#### `GetUserOrganizationInvitationsParams`
| Property | Type | Description |
| --------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialPage?` | `number` | 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`. |
| `pageSize?` | `number` | A number that specifies the maximum number of results to return per page. Defaults to `10`. |
| `status?` | `"pending" | "accepted" | "revoked" | "expired"` | The status an invitation can have. |
### `getOrganizationMemberships()`
Gets a list of Organization memberships for the user. Returns a [ClerkPaginatedResponse](https://clerk.com/docs/js-frontend/reference/types/clerk-paginated-response.md) of [OrganizationMembershipResource](https://clerk.com/docs/js-frontend/reference/types/organization-membership.md) objects.
```ts
function getOrganizationMemberships(
params?: GetUserOrganizationMembershipParams,
): Promise>
```
#### `GetUserOrganizationMembershipParams`
| Name | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| initialPage? | number | 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. |
| pageSize? | number | 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](https://clerk.com/docs/js-frontend/reference/types/clerk-paginated-response.md) of [OrganizationSuggestionResource](https://clerk.com/docs/js-frontend/reference/types/organization-suggestion.md) objects.
```typescript
function getOrganizationSuggestions(params?: GetUserOrganizationSuggestionsParams): Promise>
```
#### `GetUserOrganizationSuggestionsParams`
| Property | Type | Description |
| --------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialPage?` | `number` | 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`. |
| `pageSize?` | `number` | A number that specifies the maximum number of results to return per page. Defaults to `10`. |
| `status?` | `"pending" | "accepted" | ("pending" | "accepted")[]` | The status a suggestion can have. |
### `getPaymentMethods()`
Gets a list of payment methods that have been stored.
Returns a [ClerkPaginatedResponse](https://clerk.com/docs/js-frontend/reference/types/clerk-paginated-response.md) of [BillingPaymentMethodResource](https://clerk.com/docs/js-frontend/reference/types/billing-payment-method-resource.md) objects.
```typescript
function getPaymentMethods(params?: GetPaymentMethodsParams): Promise>
```
#### `GetPaymentMethodsParams`
| Property | Type | Description |
| --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialPage?` | `number` | 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`. |
| `pageSize?` | `number` | 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](https://clerk.com/docs/js-frontend/reference/types/session-with-activities.md) objects.
```typescript
function getSessions(): Promise
```
### `initializePaymentMethod()`
Initializes a payment method.
Returns a [BillingInitializedPaymentMethodResource](https://clerk.com/docs/js-frontend/reference/types/billing-initialized-payment-method-resource.md) object.
```typescript
function initializePaymentMethod(params: InitializePaymentMethodParams): Promise
```
#### `InitializePaymentMethodParams`
| Property | Type | Description |
| ------------------------------ | ---------- | --------------------------- |
| `gateway` | `"stripe"` | The payment gateway to use. |
### `isPrimaryIdentification()`
A check whether or not the given resource is the primary identifier for the user.
```typescript
function isPrimaryIdentification(ident: Web3WalletResource | EmailAddressResource | PhoneNumberResource): boolean
```
#### Parameters
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `ident` | Web3WalletResource | EmailAddressResource | PhoneNumberResource | The resource checked against the user to see if it is the primary identifier. |
### `leaveOrganization()`
Leaves an organization that the user is a member of.
Returns a [DeletedObjectResource](https://clerk.com/docs/js-frontend/reference/types/deleted-object-resource.md) object.
```typescript
function leaveOrganization(organizationId: string): Promise
```
#### Parameters
| Parameter | Type | Description |
| ---------------- | -------- | ------------------------------------ |
| `organizationId` | `string` | 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](https://clerk.com/docs/guides/sessions/force-token-refresh.md?sdk=js-frontend).
```typescript
function reload(p?: ClerkResourceReloadParams): Promise
```
#### `ClerkResourceReloadParams`
| Property | Type | Description |
| ----------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rotatingTokenNonce?` | `string` | 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.
```typescript
function removePassword(params: RemoveUserPasswordParams): Promise
```
#### `RemoveUserPasswordParams`
| Property | Type | Description |
| ----------------------------------------------- | -------- | ---------------------------- |
| `currentPassword?` | `string` | 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.
```typescript
function setProfileImage(params: SetProfileImageParams): Promise
```
#### `SetProfileImageParams`
| Property | Type | Description |
| ------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `file` | `Blob | File | string | null` | 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**](https://dashboard.clerk.com/~/user-authentication/user-and-authentication?user_auth_tab=user-profile) page in the Clerk Dashboard.
```typescript
function update(params: UpdateUserParams): Promise
```
#### `UpdateUserParams`
| Name | Type | Description |
| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| firstName? | string | The user's first name. |
| lastName? | string | The user's last name. |
| primaryEmailAddressId? | string | The ID for the EmailAddress that the user has set as primary. |
| primaryPhoneNumberId? | string | The ID for the PhoneNumber that the user has set as primary. |
| primaryWeb3WalletId? | string | The ID for the Web3Wallet that the user signed up with. |
| unsafeMetadata? | UserUnsafeMetadata | 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. |
| username? | string | 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()](https://clerk.com/docs/js-frontend/reference/objects/user.md#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](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}.
```typescript
function updateMetadata(params: UpdateUserMetadataParams): Promise
```
#### `UpdateUserMetadataParams`
| Property | Type | Description |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `unsafeMetadata` | [UserUnsafeMetadata](https://clerk.com/docs/js-frontend/reference/types/metadata.md#user-unsafe-metadata) | 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.
```typescript
function updatePassword(params: UpdateUserPasswordParams): Promise
```
#### `UpdateUserPasswordParams`
| Property | Type | Description |
| ------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
| `currentPassword?` | `string` | The user's current password. |
| `newPassword` | `string` | The user's new password. |
| `signOutOfOtherSessions?` | `boolean` | 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](https://clerk.com/docs/js-frontend/reference/types/totp-resource.md) object.
> The **Authenticator application** multi-factor strategy must be enabled in your app's settings in the Clerk Dashboard. See the [Multi-factor authentication](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#multi-factor-authentication) section to learn more.
```typescript
function verifyTOTP(params: VerifyTOTPParams): Promise
```
#### `VerifyTOTPParams`
| Property | Type | Description |
| ------------------------ | -------- | ------------------- |
| `code` | `string` | The code to verify. |
---
## Sitemap
[Overview of all docs pages](https://clerk.com/docs/llms.txt)