Docs

updateUser()

Updates a User.

function updateUser: (userId: string, params: UpdateUserParams) => Promise<User>;
  • 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 wallets 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
    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. Please note that 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. Please note that 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
    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,
  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
}
*/
app/api/update-user-example/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { getAuth, clerkClient } from '@clerk/nextjs/server';

// If you use `request` you don't need the type
export async function POST(req: NextRequest) {

  // Get the user ID from the session
  const { userId } = getAuth(req);

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

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

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

  return NextResponse.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 updatedUser = await clerkClient.users.updateUser(userId, params);

  return res.status(200).json({ updatedUser });
}
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 details.

Feedback

What did you think of this content?