updateUser()

Updates the mutable fields on an existing user. The SDK sends this request as multipart/form-data, which lets you update profile fields, metadata, and profile image state in one call.

Usage

The following example shows a basic usage of the backend client from @wacht/nextjs/server.

import { wachtClient } from '@wacht/nextjs/server';export async function disableUser(userId: string) {  const client = await wachtClient();  return client.users.updateUser(userId, {    disabled: true,  });}

Signature

function updateUser(  userId: string,  request: UpdateUserRequest,): Promise<UserDetails>

Parameters

›

userId?: string | undefined;

Stable id of the user to update.

›

request?: UpdateUserRequest | undefined;

Multipart update payload containing the fields you want to change.

›

first_name?: string | undefined;

Updated first name. The backend ignores empty strings here rather than treating them as a clear operation.

›

last_name?: string | undefined;

Updated last name. The backend ignores empty strings here rather than treating them as a clear operation.

›

username?: string | undefined;

Updated username. Depending on deployment auth settings, username validation rules may still apply.

›

public_metadata?: Record<string, unknown> | undefined;

Replacement public metadata object for the user.

›

tier?: string | undefined;

Example public tier/plan field.

›

segment?: string | undefined;

Example public segment label.

›

private_metadata?: Record<string, unknown> | undefined;

Replacement private metadata object for the user.

›

internal_notes?: string | undefined;

Example internal note field.

›

risk_score?: number | undefined;

Example internal risk score.

›

disabled?: boolean | undefined;

When `true`, disables the user. The backend also deletes existing sign-ins for that user when this is set to `true`.

›

remove_profile_image?: boolean | undefined;

When `true`, removes the stored profile image.

›

profile_image?: File | Blob | undefined;

Optional replacement profile image uploaded with the update request.

Return value

›

id?: string | undefined;

Stable user identifier.

›

created_at?: string | undefined;

Creation timestamp.

›

updated_at?: string | undefined;

Last update timestamp.

›

first_name?: string | undefined;

Current first name after the update.

›

last_name?: string | undefined;

Current last name after the update.

›

username?: string | undefined;

Current username when one exists.

›

profile_picture_url?: string | undefined;

Current profile image URL after any upload or removal logic has been applied.

›

disabled?: boolean | undefined;

Whether the user is currently disabled.

›

public_metadata?: Record<string, unknown> | undefined;

Current public metadata object.

›

tier?: string | undefined;

Example public tier/plan field.

›

segment?: string | undefined;

Example public segment label.

›

private_metadata?: Record<string, unknown> | undefined;

Current private metadata object.

›

internal_notes?: string | undefined;

Example internal note field.

›

risk_score?: number | undefined;

Example internal risk score.

›

primary_email_address?: string | undefined;

Current primary email address string when one exists.

›

primary_phone_number?: string | undefined;

Current primary phone number string when one exists.

›

email_addresses?: UserEmail[] | undefined;

Resolved user email addresses included in the detailed response.

›

phone_numbers?: UserPhone[] | undefined;

Resolved user phone numbers included in the detailed response.

›

social_connections?: UserSocialConnection[] | undefined;

Linked social connections included in the detailed response.

›

segments?: Segment[] | undefined;

Segments currently attached to the user.

›

has_password?: boolean | undefined;

Whether the user currently has a password set.

›

has_backup_codes?: boolean | undefined;

Whether the user currently has backup codes generated.

What the backend does

The backend updates the user record first and then re-queries the full UserDetails payload, so the response is a detailed post-update snapshot rather than the smaller list-style User shape.

If you set remove_profile_image, the backend clears the stored image and then reloads the user. If you upload a new profile_image, the backend uploads it after the record update and then reloads the user again.

Metadata fields replace their stored values

When you send public_metadata or private_metadata, the backend treats them as the new stored metadata values for that field.

If you need to preserve part of an existing metadata object, read it first and merge it on your side before calling updateUser().

Disabling a user is a stronger action than a normal profile edit

When disabled is set to true, the backend also deletes the user existing sign-ins as part of the update flow.

That makes updateUser({ disabled: true }) the right administrative action for cutting off access without permanently deleting the user record.

Examples

Disable a user

import { wachtClient } from '@wacht/nextjs/server';export async function disableUser(userId: string) {  const client = await wachtClient();  return client.users.updateUser(userId, {    disabled: true,  });}

Update profile fields and metadata

import { wachtClient } from '@wacht/nextjs/server';export async function updateUserProfile(userId: string) {  const client = await wachtClient();  return client.users.updateUser(userId, {    first_name: 'Ada',    last_name: 'Byron',    public_metadata: {      title: 'Administrator',      team: 'platform',    },  });}

Replace the profile image

import { wachtClient } from '@wacht/nextjs/server';export async function updateUserProfileImage(userId: string, file: File) {  const client = await wachtClient();  return client.users.updateUser(userId, {    profile_image: file,  });}

Remove the profile image

import { wachtClient } from '@wacht/nextjs/server';export async function removeUserProfileImage(userId: string) {  const client = await wachtClient();  return client.users.updateUser(userId, {    remove_profile_image: true,  });}