Update Username

Audience: Low-code Engineers

Skill Prerequisites: Actions, User management

Changes a user's username. It changes the user in User Identifier. If that's empty, it changes the current user. That's the logged-in user, or the user set by Load User or Change User.

It isn't available in Automation.

Typical Use Cases

• Let users pick a new username on a "My Account" form
• Keep usernames in sync with email addresses on sites that use the email as the username
• Rename a user from an admin form or Listing

Don't use it to

• Change the email, display name or other profile data. Use Update User Profile instead.
• Change a superuser's (host's) username. The action doesn't allow it.

Related Actions

Action Name	Description
Update User Profile	Changes the password, display name, email and profile properties.
Load User	Makes a user the current user.
Change User	Changes the current user for the actions that follow.
User Registration	Creates a new user with a username.

Input Parameter Reference

The parameters unique to this action are listed below. Review the common parameters for all actions here.

Parameter	Description	Supports Tokens	Default	Required
User Identifier	The user to change, as a user ID, email or username. Leave it empty to change the current user. See How the user is found.	Yes	empty string	No
New Username	The new username, for example [NewUsername]. If it's empty, the action fails with No new user name was provided.	Yes	empty string	Yes

Output Parameters Reference

This action doesn't create any tokens.

How the user is found

User Identifier is looked up on the current portal in this order:

1. If it's a number, it's treated as a user ID.
2. Otherwise, it's matched against email addresses.
3. If no email matches, it's matched against usernames.

If no user is found, the action fails. If the user found is a superuser, the action fails with You're not allowed to change the Username of a SuperUser. End users see a general "Something went wrong" message instead.

Considerations

• Email as username. If the portal is set to use the email address as the username, the new username must be a valid email address. Otherwise, the action fails with The username does not meet the required format. Update the user's email with Update User Profile too, so both stay the same.
• Check that the name is free. The action doesn't check if another user already has the new username. Check it first, for example with Run SQL Query, and show a message if it's taken.
• Check who can run it. The action doesn't check if the person running it may change the target user. If User Identifier comes from a form field, the URL or an API request, anyone who can submit it can rename another user. On public forms, leave User Identifier empty so users only rename themselves.
• Empty after tokens. The current user is used only when User Identifier is empty as typed. If it holds a token that turns out empty, the action looks for a user with an empty identifier and fails.
• Users log in with the new name. Tell the user their new username, for example with Send Email.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Let users change their own username

This action runs on a form's submit button. It changes the logged-in user's username to the value of the NewUsername field. It only runs when the field isn't empty.

{
    "Title": "Update Username",
    "ActionType": "UserManagement_ChangeUsername",
    "Description": "Change the logged-in user's username",
    "Condition": "[NewUsername] != \"\"",
    "Parameters": {
        "UserIdentifier": "",
        "NewUserName": "[NewUsername]"
    }
}

2. Use the new email as the username

This action changes the username of the user with the ID in the UserId field to the email in the Email field. Use it after Update User Profile changes the email, on a site that uses the email as the username.

{
    "Title": "Update Username",
    "ActionType": "UserManagement_ChangeUsername",
    "Description": "Set the username to the new email",
    "Parameters": {
        "UserIdentifier": "[UserId]",
        "NewUserName": "[Email]"
    }
}

Revised 09/28/2026