UpdateUserParams
Example
1. Examples with frameworks
Backend API (BAPI) endpoint

`updateUser()`

Updates a User.

function updateUser(userId: string, params: UpdateUserParams): Promise<User>

`UpdateUserParams`

Name
userId
Type
string
Description
The ID of the user to update.
Name
externalId?
Type
string
Description
The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance.
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 of the email address to set as primary. It must be verified, and present on the current user.
Name
notifyPrimaryEmailAddressChanged?
Type
boolean
Description
If set to true, the user will be notified that their primary email address has changed. By default, no notification is sent. Defaults to false.
Name
primaryPhoneNumberID?
Type
string
Description
The ID of the phone number to set as primary. It must be verified, and present on the current user.
Name
primaryWeb3WalletID?
Type
string
Description
The ID of the Web3 wallet to set as primary. It must be verified, and present on the current user.
Name
username?
Type
string
Description
The user's username. It must be unique across your instance.
Name
be used when providing a password.
Description
Name
profileImageID?
Type
string
Description
The ID of the image to set as the user's profile image.
Name
password?
Type
string
Description
The plaintext password to give the user. Must be at least 8 characters long, and can not be in any list of hacked passwords.
Name
passwordDigest?
Type
string
Description
In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. The digests should be generated with one of the supported algorithms. The hashing algorithm can be specified using the password_hasher property.
Name
passwordHasher?
Type
'argon2i' | 'argon2id' | 'bcrypt' | 'bcrypt_sha256_django' | 'md5' | 'pbkdf2_sha256' | 'pbkdf2_sha256_django' | 'pbkdf2_sha1' | 'phpass' | 'scrypt_firebase' | 'scrypt_werkzeug' | 'sha256'
Description
The hashing algorithm that was used to generate the password digest. Each of the supported hashers expects the incoming digest to be in a particular format. See the Clerk Backend API reference for more information.
Name
skipPasswordChecks?
Type
boolean
Description
When set to true, all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password.
Name
skipPasswordRequirement?
Type
boolean
Description
When set to true, password is not required anymore when creating the user and can be omitted. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. You cannot use this flag if password is the only way for a user to sign into your instance.
Name
signOutOfOtherSessions?
Type
boolean
Description
Set to true to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a password.
Name
totpSecret?
Type
string
Description
In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. Currently, the supported options are:
Period: 30 seconds
Code length: 6 digits
Algorithm: SHA1
Name
backupCodes?
Type
string[]
Description
If backup codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest.
Name
publicMetadata?
Type
Record<string, unknown>
Description
Metadata saved on the user, that is visible to both your Frontend and Backend APIs.
Name
privateMetadata?
Type
Record<string, unknown>
Description
Metadata saved on the user that is only visible to your Backend API.
Name
unsafeMetadata?
Type
Record<string, unknown>
Description
Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
Name
deleteSelfEnabled?
Type
boolean
Description
If true, the user can delete themselves with the Frontend API.
Name
createOrganizationEnabled?
Type
boolean
Description
If true, the user can create organizations with the Frontend API.
Name
createOrganizationsLimit?
Type
number
Description
An integer indicating the number of organizations that can be created by the user. If the value is 0, then the user can create unlimited organizations. Default is null.
Name
createdAt?
Type
Date
Description
A custom date/time denoting when the user signed up to the application, specified in RFC3339 format

For example: 2012-10-20T07:15:20.902Z.

Example

In this example, you can see that the response is the updated User object, with a firstName and lastName of "John" and "Wick" respectively.

const userId = 'user_123'

const params = { firstName: 'John', lastName: 'Wick' }

const response = await clerkClient.users.updateUser(userId, params)

console.log(response)
/*
_User {
  id: 'user_123',
  passwordEnabled: false,
  totpEnabled: false,
  backupCodeEnabled: false,
  twoFactorEnabled: false,
  banned: false,
  locked: false,
  createdAt: 1719935072474,
  updatedAt: 1720205925110,
  imageUrl: 'https://img.clerk.com/eyJ...',
  hasImage: true,
  primaryEmailAddressId: 'idn_123',
  primaryPhoneNumberId: null,
  primaryWeb3WalletId: null,
  lastSignInAt: 1720205704411,
  externalId: null,
  username: null,
  firstName: 'John',
  lastName: 'Wick',
  publicMetadata: {},
  privateMetadata: {},
  unsafeMetadata: {},
  emailAddresses: [
    _EmailAddress {
      id: 'idn_123',
      emailAddress: 'testclerk123@gmail.com',
      verification: [_Verification],
      linkedTo: [Array]
    }
  ],
  phoneNumbers: [],
  web3Wallets: [],
  externalAccounts: [
    _ExternalAccount {
      id: 'idn_123',
      provider: undefined,
      identificationId: undefined,
      externalId: undefined,
      approvedScopes: 'email https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid profile',
      emailAddress: 'testclerk123@gmail.com',
      firstName: undefined,
      lastName: undefined,
      imageUrl: '',
      username: '',
      publicMetadata: {},
      label: null,
      verification: [_Verification]
    }
  ],
  samlAccounts: [],
  lastActiveAt: 1720205704451,
  createOrganizationEnabled: true
}
*/

Examples with frameworks

Next.js

Node

Remix

App Router

Pages Router

app/api/update-user-example/route.ts

import { auth, clerkClient } from '@clerk/nextjs/server'

export async function POST() {
  // Get the user ID from the session
  const { userId } = await auth()

  if (!userId) return Response.redirect('/sign-in')

  // The user attributes to update
  const params = { firstName: 'John', lastName: 'Wick' }

  const client = await clerkClient()

  const updatedUser = await client.users.updateUser(userId, params)

  return Response.json({ updatedUser })
}

pages/api/updateUser.tsx

import { clerkClient, getAuth } from '@clerk/nextjs/server'
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // Get the user ID from the session
  const { userId } = getAuth(req)

  if (!userId) {
    return res.status(500).json({ error: 'No valid user' })
  }

  // The user attributes to update
  const params = { firstName: 'John', lastName: 'Wick' }

  const client = await clerkClient()

  const updatedUser = await client.users.updateUser(userId, params)

  return res.status(200).json({ updatedUser })
}

Caution

On January 8, 2025, the Node SDK will no longer be available. Upgrade to the Express SDK.

updateUser.js

import { clerkClient } from '@clerk/clerk-sdk-node'

app.post(
  '/api/update-user',
  // ClerkExpressRequireAuth returns an error for unauthorized requests
  ClerkExpressRequireAuth(),

  // Optionally ClerkExpressWithAuth returns an empty user with no error
  // ClerkExpressWithAuth(),

  async (req, res) => {
    // Get the user ID from req.auth
    const userId = req.auth.userId

    // The user attributes to update
    const params = { firstName: 'John', lastName: 'Wick' }

    const updatedUser = await clerkClient.users.updateUser(userId, params)

    res.json({ updatedUser })
  },
)

app/routes/profile.tsx

import { createClerkClient } from '@clerk/remix/api.server'
import { getAuth } from '@clerk/remix/ssr.server'
import { ActionFunction, json } from '@remix-run/node'

export const action: ActionFunction = async (req) => {
  // Get the user ID from the session
  const { userId } = await getAuth(req)

  // The user attributes to update
  const params = { firstName: 'John', lastName: 'Wick' }

  const updatedUser = await createClerkClient({
    secretKey: process.env.CLERK_SECRET_KEY,
  }).users.updateUser(userId, params)

  return json({ updatedUser })
}

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint PATCH/users/{user_id}. See the BAPI reference for more information.

Edit this page on GitHub

Last updated on Nov 18, 2024

updateUser()

UpdateUserParams

Example

Examples with frameworks

Backend API (BAPI) endpoint

Feedback

`updateUser()`

`UpdateUserParams`