useUser

Manage user profile, email addresses, phone numbers, and security settings.

useUser

The useUser hook provides methods for managing the current user’s profile, email addresses, phone numbers, passwords, and two-factor authentication settings.

Return Value

user · User | null

The current user object

loading · boolean

Whether user data is loading

error · Error | null

Any error that occurred

refetch

Show Refetch user data from server

returns · Promise<void>

Resolves when user data is refetched

updateProfile

Show Update the user's profile information

params · Partial<User>

User fields to update (first_name, last_name, username, profile_picture_url)

returns · Promise<User>

The updated user

getEmailAddresses

Show Get all email addresses

returns · Promise<EmailAddress[]>

List of email addresses

getEmailAddress

Show Get a specific email address

id · string

The email address ID

returns · Promise<EmailAddress>

The email address

createEmailAddress

Show Add a new email address

email · string

The email address to add

returns · Promise<EmailAddress>

The created email address

deleteEmailAddress

Show Remove an email address

id · string

The ID of the email address to remove

returns · Promise<void>

Resolves when the email address is removed

prepareEmailVerification

Show Send verification code to email

id · string

The ID of the email address to verify

returns · Promise<void>

Resolves when the verification code is sent

attemptEmailVerification

Show Verify email with OTP code

id · string

The ID of the email address to verify

otp · string

The OTP verification code

returns · Promise<void>

Resolves when the email is verified

makeEmailPrimary

Show Set an email as primary

id · string

The ID of the email address to set as primary

returns · Promise<void>

Resolves when the email is set as primary

createPhoneNumber

Show Add a phone number

phone_number · string

The phone number in E.164 format

country_code · string

The ISO country code (e.g., “US”)

returns · Promise<PhoneNumber>

The created phone number

deletePhoneNumber

Show Remove a phone number

id · string

The ID of the phone number to remove

returns · Promise<void>

Resolves when the phone number is removed

preparePhoneVerification

Show Send verification code to phone

id · string

The ID of the phone number to verify

returns · Promise<void>

Resolves when the verification code is sent

attemptPhoneVerification

Show Verify phone with code

id · string

The ID of the phone number to verify

otp · string

The OTP verification code

returns · Promise<void>

Resolves when the phone is verified

makePhonePrimary

Show Set a phone number as primary

id · string

The ID of the phone number to set as primary

returns · Promise<void>

Resolves when the phone is set as primary

updatePassword

Show Change password

currentPassword · string

The current password

newPassword · string

The new password

returns · Promise<void>

Resolves when the password is updated

removePassword

Show Remove password (passkeys/OAuth only)

currentPassword · string

The current password (required to confirm removal)

returns · Promise<void>

Resolves when the password is removed

deleteAccount

Show Delete the user account

password · string

The current password (required to confirm deletion)

returns · Promise<void>

Resolves when the account is deleted

connectSocialAccount

Show Connect a social account

params · { provider: string; redirectUri?: string }

OAuth connection parameters

returns · Promise<void>

Initiates the OAuth flow

disconnectSocialConnection

Show Disconnect a social account

id · string

The ID of the social connection to remove

returns · Promise<void>

Resolves when the connection is removed

getPasskeys

Show Get all passkeys

returns · Promise<UserPasskey[]>

List of passkeys

registerPasskey

Show Register a new passkey

name · string

Optional name for the passkey

returns · Promise<UserPasskey>

The registered passkey

deletePasskey

Show Remove a passkey

id · string

The ID of the passkey to remove

returns · Promise<void>

Resolves when the passkey is removed

renamePasskey

Show Rename a passkey

id · string

The ID of the passkey to rename

name · string

The new name for the passkey

returns · Promise<void>

Resolves when the passkey is renamed

setupAuthenticator

Show Begin TOTP authenticator setup

returns · Promise<UserAuthenticator>

The authenticator with QR code URI and secret

verifyAuthenticator

Show Complete TOTP setup with verification codes

id · string

The authenticator ID

codes · string[]

Array of 6-digit TOTP codes

returns · Promise<void>

Resolves when the authenticator is verified

deleteAuthenticator

Show Remove TOTP authenticator

id · string

The authenticator ID

returns · Promise<void>

Resolves when the authenticator is removed

generateBackupCodes

Show Generate backup codes for 2FA

returns · Promise<string[]>

List of backup codes

regenerateBackupCodes

Show Regenerate backup codes

returns · Promise<string[]>

New list of backup codes (invalidates old ones)

updateProfilePicture

Show Update the user's profile picture

file · File

The image file to upload

returns · Promise<User>

The updated user

Profile Management

updateProfile

Update the user’s profile information.

first_name · string

New first name

last_name · string

New last name

username · string

New username

profile_picture_url · string

URL to profile picture

await updateProfile({
  first_name: "Jane",
  last_name: "Doe",
  username: "janedoe",
});

Email Management

createEmailAddress

Add a new email address to the user account.

email · string · required

The email address to add

await createEmailAddress("[e-mail]");

deleteEmailAddress

Remove an email address from the user account.

id · string · required

The ID of the email address to remove

prepareEmailVerification

Send a verification code to the specified email address.

id · string · required

The ID of the email address to verify

attemptEmailVerification

Verify an email address with an OTP code.

id · string · required

The ID of the email address to verify

otp · string · required

The OTP verification code

// Send verification code
await prepareEmailVerification("email_id_123");

// Submit verification code
await attemptEmailVerification("email_id_123", "123456");

Phone Management

createPhoneNumber

Add a new phone number to the user account.

phone_number · string · required

The phone number in E.164 format

country_code · string · required

The ISO country code (e.g., “US”)

await createPhoneNumber("[phone]", "US");

deletePhoneNumber

Remove a phone number from the user account.

id · string · required

The ID of the phone number to remove

preparePhoneVerification

Send a verification code to the specified phone number.

id · string · required

The ID of the phone number to verify

attemptPhoneVerification

Verify a phone number with an OTP code.

id · string · required

The ID of the phone number to verify

otp · string · required

The OTP verification code

// Send verification code
await preparePhoneVerification("phone_id_123");

// Submit verification code
await attemptPhoneVerification("phone_id_123", "123456");

makePhonePrimary

Set a phone number as the primary phone number for the account.

id · string · required

The ID of the phone number to set as primary

makeEmailPrimary

Set an email address as the primary email address for the account.

id · string · required

The ID of the email address to set as primary

Password Management

updatePassword

Change the user’s password.

currentPassword · string · required

The current password

newPassword · string · required

The new password

await updatePassword("oldPassword123", "newPassword456");

removePassword

Remove the user’s password. After removal, the user can only sign in with passkeys or OAuth.

currentPassword · string · required

The current password (required to confirm removal)

await removePassword("currentPassword123");

deleteAccount

Delete the user’s account permanently.

password · string · required

The current password (required to confirm deletion)

await deleteAccount("currentPassword123");

Passkey Management

registerPasskey

Register a new passkey for the user using WebAuthn. The name parameter is optional.

await registerPasskey("My MacBook Pro");
// or without a name
await registerPasskey();

deletePasskey

Remove a passkey from the user account.

id · string · required

The ID of the passkey to remove

renamePasskey

Rename a passkey for easier identification.

id · string · required

The ID of the passkey to rename

name · string · required

The new name for the passkey

await renamePasskey("passkey_id_123", "My Work Laptop");

getPasskeys

Get all passkeys registered to the user account.

const passkeys = await getPasskeys();

Profile Picture

updateProfilePicture

Update the user’s profile picture.

file · File · required

The image file to upload

await updateProfilePicture(fileInput.files[0]);

Social Connections

connectSocialAccount

Connect a social account (OAuth provider) to the user account.

provider · string · required

The OAuth provider (e.g., “google_oauth”, “github_oauth”)

redirectUri · string

Optional redirect URI after OAuth flow

await connectSocialAccount({ provider: "google_oauth" });

disconnectSocialConnection

Disconnect a social account from the user account.

id · string · required

The ID of the social connection to remove

await disconnectSocialConnection("connection_id_123");

Two-Factor Authentication

setupAuthenticator

Begin TOTP authenticator setup. Returns a QR code URI and secret key.

const authenticator = await setupAuthenticator();
// authenticator contains: id, uri (for QR code), secret

verifyAuthenticator

Complete TOTP setup with verification codes.

id · string · required

The authenticator ID

codes · string[] · required

Array of 6-digit TOTP codes

await verifyAuthenticator("authenticator_id", ["123456", "234567"]);

deleteAuthenticator

Remove TOTP authenticator from the user account.

await deleteAuthenticator("authenticator_id");

generateBackupCodes

Generate backup codes for 2FA recovery.

const codes = await generateBackupCodes();
// Save these codes securely

regenerateBackupCodes

Regenerate backup codes (invalidates old ones).

const newCodes = await regenerateBackupCodes();

Related

• UserButton - User account button
• useSession - Session management