Skip to main content

updateUser()

Updates the given User.

function updateUser(userId: string, params: { backupCodes?: string[]; createdAt?: Date; createOrganizationEnabled?: boolean; createOrganizationsLimit?: number; deleteSelfEnabled?: boolean; externalId?: string; firstName?: string; lastName?: string; legalAcceptedAt?: Date; locale?: string; notifyPrimaryEmailAddressChanged?: boolean; password?: string; primaryEmailAddressID?: string; primaryPhoneNumberID?: string; primaryWeb3WalletID?: string; privateMetadata?: UserPrivateMetadata; profileImageID?: string; publicMetadata?: UserPublicMetadata; signOutOfOtherSessions?: boolean; skipLegalChecks?: boolean; skipPasswordChecks?: boolean; totpSecret?: string; unsafeMetadata?: UserUnsafeMetadata; username?: string } & object | { backupCodes?: string[]; createdAt?: Date; createOrganizationEnabled?: boolean; createOrganizationsLimit?: number; deleteSelfEnabled?: boolean; externalId?: string; firstName?: string; lastName?: string; legalAcceptedAt?: Date; locale?: string; notifyPrimaryEmailAddressChanged?: boolean; password?: string; primaryEmailAddressID?: string; primaryPhoneNumberID?: string; primaryWeb3WalletID?: string; privateMetadata?: UserPrivateMetadata; profileImageID?: string; publicMetadata?: UserPublicMetadata; signOutOfOtherSessions?: boolean; skipLegalChecks?: boolean; skipPasswordChecks?: boolean; totpSecret?: string; unsafeMetadata?: UserUnsafeMetadata; username?: string } & { passwordDigest: string; passwordHasher: "argon2i" | "argon2id" | "awscognito" | "bcrypt" | "bcrypt_sha256_django" | "md5" | "pbkdf2_sha256" | "pbkdf2_sha256_django" | "pbkdf2_sha1" | "phpass" | "scrypt_firebase" | "scrypt_werkzeug" | "sha256" | "md5_phpass" | "ldap_ssha" }): Promise<User>

Parameters

  • Name
    userId
    Type
    string
    Description

    The ID of the user to update.

  • Name
    params
    Type
    { backupCodes?: string[]; createdAt?: Date; createOrganizationEnabled?: boolean; createOrganizationsLimit?: number; deleteSelfEnabled?: boolean; externalId?: string; firstName?: string; lastName?: string; legalAcceptedAt?: Date; locale?: string; notifyPrimaryEmailAddressChanged?: boolean; password?: string; primaryEmailAddressID?: string; primaryPhoneNumberID?: string; primaryWeb3WalletID?: string; privateMetadata?: UserPrivateMetadata; profileImageID?: string; publicMetadata?: UserPublicMetadata; signOutOfOtherSessions?: boolean; skipLegalChecks?: boolean; skipPasswordChecks?: boolean; totpSecret?: string; unsafeMetadata?: UserUnsafeMetadata; username?: string; } & object | { backupCodes?: string[]; createdAt?: Date; createOrganizationEnabled?: boolean; createOrganizationsLimit?: number; deleteSelfEnabled?: boolean; externalId?: string; firstName?: string; lastName?: string; legalAcceptedAt?: Date; locale?: string; notifyPrimaryEmailAddressChanged?: boolean; password?: string; primaryEmailAddressID?: string; primaryPhoneNumberID?: string; primaryWeb3WalletID?: string; privateMetadata?: UserPrivateMetadata; profileImageID?: string; publicMetadata?: UserPublicMetadata; signOutOfOtherSessions?: boolean; skipLegalChecks?: boolean; skipPasswordChecks?: boolean; totpSecret?: string; unsafeMetadata?: UserUnsafeMetadata; username?: string; } & { passwordDigest: string; passwordHasher: "argon2i" | "argon2id" | "awscognito" | "bcrypt" | "bcrypt_sha256_django" | "md5" | "pbkdf2_sha256" | "pbkdf2_sha256_django" | "pbkdf2_sha1" | "phpass" | "scrypt_firebase" | "scrypt_werkzeug" | "sha256" | "md5_phpass" | "ldap_ssha"; }
    Description

    The user attributes to update.

  • Name
    params.backupCodes?
    Type
    string[]
    Description

    If backup codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest.

  • Name
    params.createdAt?
    Type
    Date
    Description

    A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g. '2012-10-20T07:15:20.902Z').

  • Name
    params.createOrganizationEnabled?
    Type
    boolean
    Description

    If true, the user can create Organizations with the Frontend API.

  • Name
    params.createOrganizationsLimit?
    Type
    number
    Description

    The maximum number of Organizations the user can create. 0 means unlimited.

  • Name
    params.deleteSelfEnabled?
    Type
    boolean
    Description

    If true, the user can delete themselves with the Frontend API.

  • Name
    params.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 entire instance.

  • Name
    params.firstName?
    Type
    string
    Description

    The first name to assign to the user.

  • Name
    params.lastName?
    Type
    string
    Description

    The last name to assign to the user.

  • Name
    params.legalAcceptedAt?
    Type
    Date
    Description

    A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. '2012-10-20T07:15:20.902Z').

  • Name
    params.locale?
    Type
    string
    Description

    The locale of the user in BCP-47 format (e.g. 'en-US').

  • Name
    params.notifyPrimaryEmailAddressChanged?
    Type
    boolean
    Description

    When set to true, the user is notified that their primary email address has changed.

  • Name
    params.password?
    Type
    string
    Description

    The plaintext password to assign to the user. Must be at least 8 characters long, and can not be in any list of hacked passwords.

  • Name
    params.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
    params.passwordHasher
    Type
    "argon2i" | "argon2id" | "awscognito" | "bcrypt" | "bcrypt_sha256_django" | "md5" | "pbkdf2_sha256" | "pbkdf2_sha256_django" | "pbkdf2_sha1" | "phpass" | "scrypt_firebase" | "scrypt_werkzeug" | "sha256" | "md5_phpass" | "ldap_ssha"
    Description

    The hashing algorithm that was used to generate the password digest. Must be one of the supported algorithms. For password hashers considered insecure (currently, md5, md5_salted, sha256, sha256_salted, sha512_symfony), the corresponding user password hashes will be transparently migrated to bcrypt (a secure hasher) upon the user's first successful password sign in. Insecure schemes are marked with (insecure) in the list below.

    • awscognito
      • When set, password_digest must be in the format of awscognito#<userpoolid>#<clientid>#<identifier>.
      • Upon a successful migration, password_hasher will be updated to bcrypt, and password_digest will be updated to a bcrypt hash.
      • See the migration guide for usage details.
    • bcrypt
      • When set, password_digest must be in the format of $<algorithm version>$<cost>$<salt & hash>.
    • bcrypt_sha256_django
      • This is the Django-specific variant of Bcrypt, using SHA256 hashing function. When set, password_digest must be in the format of (as exported from Django): bcrypt_sha256$$<algorithm version>$<cost>$<salt & hash>.
    • bcrypt_peppered
      • Used in implementations such as Devise for Ruby on Rails applications. Identical to bcrypt except that a pepper string is appended to the input before hashing. When set, password_digest must be in the format of $<algorithm version>$<cost>$<salt & hash>$<pepper>.
    • md5 (insecure)
      • When set, password_digest must be in the format of 5f4dcc3b5aa765d61d8327deb882cf99.
    • md5_salted (insecure)
      • When set, password_digest must be in the format of salt$hash.
      • salt: The salt used to generate the above hash.
      • hash: A 32-length hex string.
    • pbkdf2_sha1
      • When set, password_digest must be in the format of pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string> or pbkdf2_sha1$<iterations>$<salt-as-hex-string>$<hash-as-hex-string>$<key-length>.
      • Accepts the salt as a hex-encoded string. If the salt is not a valid hex string, the raw bytes will be used instead. Accepts the hash as a hex-encoded string. Optionally accepts the key length as the last parameter (defaults to 32).
    • pbkdf2_sha256
      • This is the PBKDF2 algorithm using the SHA256 hashing function. When set, password_digest must be in the format of pbkdf2_sha256$<iterations>$<salt>$<hash>.
      • Both the salt and the hash are expected to be base64-encoded.
    • pbkdf2_sha512
      • This is the PBKDF2 algorithm using the SHA512 hashing function. When set, password_digest must be in the format of pbkdf2_sha512$<iterations>$<salt>$<hash>.
      • The salt is expected to be an unencoded string literal, and the hash should be hex-encoded.
    • pbkdf2_sha512_hex
      • This is the PBKDF2 algorithm using the SHA512 hashing function. When set, password_digest must be in the format of pbkdf2_sha512_hex$<iterations>$<salt>$<hash>.
      • Both the salt and the hash are expected to be hex-encoded.
    • pbkdf2_sha256_django
      • This is the Django-specific variant of PBKDF2. When set, password_digest must be in the format of (as exported from Django): pbkdf2_sha256$<iterations>$<salt>$<hash>.
      • The salt is expected to be un-encoded, the hash is expected base64-encoded.
    • phpass
      • Portable public domain password hashing framework for use in PHP applications. When set, password_digest must be in the format of $P$<rounds><salt><encoded-checksum>.
      • $P$ is the prefix used to identify phpass hashes.
      • rounds: A single character encoding a 6-bit integer representing the number of rounds used.
      • salt: Eight characters drawn from [./0-9A-Za-z], providing a 48-bit salt.
      • encoded-checksum: 22 characters drawn from the same set, encoding the 128-bit checksum with MD5.
    • scrypt_firebase
      • The Firebase-specific variant of scrypt. When set, password_digest must be in the format of <hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>.
      • hash: The actual Base64 hash. This can be retrieved when exporting the user from Firebase.
      • salt: The salt used to generate the above hash. Again, this is given when exporting the user from Firebase.
      • signer key: The base64 encoded signer key.
      • salt separator: The base64 encoded salt separator.
      • rounds: The number of rounds the algorithm needs to run.
      • memory cost: The cost of the algorithm run.
    • scrypt_werkzeug
      • The Werkzeug-specific variant of scrypt. When set, password_digest must be in the format of $<algorithm args>$<salt>$<hash>.
      • algorithm args: The algorithm used to generate the hash.
      • salt: The salt used to generate the above hash.
      • hash: The actual Base64 hash.
    • sha256 (insecure)
      • When set, password_digest must be a 64-length hex string. For example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.
    • sha256_salted (insecure)
      • When set, password_digest must be in the format of salt$hash.
      • salt: The salt used to generate the above hash.
      • hash: A 64-length hex string.
    • argon2 variants: argon2i and argon2id.
      • Parts are demarcated by the $ character, with the first part identifying the algorithm variant The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism). The final part is the actual digest.
      • When set, password_digest must be in the format of $argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc.
      • For the argon2id case, the value of the algorithm in the first part of the digest is argon2id: $argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU.
    • sha512_symfony (insecure)
      • The legacy Symfony MessageDigestPasswordEncoder algorithm. We currently only support the SHA512 variant. When set, password_digest must be in the format of sha512_symfony$iterations$salt$hash.
      • iterations: A number greater than 0.
      • salt: The salt used to generate the above hash.
      • hash: The actual Base64 hash.

    If you need support for any particular hashing algorithm, contact support.

  • Name
    params.primaryEmailAddressID?
    Type
    string
    Description

    The ID of the email address to set as primary. Must be verified and present on the given user.

  • Name
    params.primaryPhoneNumberID?
    Type
    string
    Description

    The ID of the phone number to set as primary. Must be verified and present on the given user.

  • Name
    params.primaryWeb3WalletID?
    Type
    string
    Description

    The ID of the web3 wallets to set as primary. Must be verified and present on the given user.

  • Name
    params.privateMetadata?
    Type
    UserPrivateMetadata
    Description

    Deprecated. Updating metadata via updateUser() is deprecated. Use updateUserMetadata() for partial updates (deep merge) or replaceUserMetadata() for full replacement.

  • Name
    params.profileImageID?
    Type
    string
    Description

    The ID of the image to set as the user's profile image.

  • Name
    params.publicMetadata?
    Type
    UserPublicMetadata
    Description

    Deprecated. Updating metadata via updateUser() is deprecated. Use updateUserMetadata() for partial updates (deep merge) or replaceUserMetadata() for full replacement.

  • Name
    params.signOutOfOtherSessions?
    Type
    boolean
    Description

    When set to true, the user is signed out from all their active sessions once their password is updated.

  • Name
    params.skipLegalChecks?
    Type
    boolean
    Description

    When set to true, all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk.

  • Name
    params.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
    params.totpSecret?
    Type
    string
    Description

    In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it. Currently, the supported options are:

    • Period: 30 seconds
    • Code length: 6 digits
    • Algorithm: SHA1
  • Name
    params.unsafeMetadata?
    Type
    UserUnsafeMetadata
    Description

    Deprecated. Updating metadata via updateUser() is deprecated. Use updateUserMetadata() for partial updates (deep merge) or replaceUserMetadata() for full replacement.

  • Name
    params.username?
    Type
    string
    Description

    The username to assign to the user. Must be unique across your instance.

Usage

Note

Using clerkClient varies based on the SDK you're using. Refer to the overview for usage details, including guidance on how to access the userId and other properties.

const userId = 'user_123'

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

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

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.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub