3 Ways to Change a User's Google Workspace Username

Changing a Google Workspace username can affect sign-in, the primary email address, aliases, and directory sync. It’s a routine admin task when someone changes names or moves teams, but the impact varies by scale and tooling.

I’ll walk you step-by-step through three methods, Admin Console edits, bulk updates via CSV, and the Directory/Admin SDK API, so you can pick the right approach, handle permissions, and avoid downtime.

Table of Contents

• Use Google Workspace's UI
• Use Torii
• Use Google Workspace's API

Use Google Workspace’s UI

Here you’ll use the Google Workspace Admin console to change a user’s name or primary email address. These steps follow Google Workspace’s admin instructions for renaming users.

Open the Admin console

• Sign in to admin.google.com with an admin account that has user management rights.
• From the Admin console home, click Users.

Find the user

• In the Users list, locate the person by name or email.
• Click the user’s row to open their account page.

Rename the user (change display name or primary email)

• On the user’s account page, click User information or the Account card.
• Click Rename or the edit icon next to the name.
• Change the First name and Last name to update the display name.
• To change the sign-in address, edit the primary email field to the new username or domain.
• Click Rename or Save to apply the change.

What to expect after renaming

• If you change the primary email, the user must sign in with the new address going forward.
• Google Workspace typically converts the old primary email into an email alias for the user automatically, unless that address is already in use.
• Mail sent to the old address should still arrive, but you may want to confirm aliases after the change.

Quick checks and follow-up

• Tell the user about the new sign-in email and have them update any saved logins or mobile apps.
• Check shared resources and third-party apps that identify users by email. Update any settings that use the old address if needed.
• For full details and troubleshooting steps, see the Google Workspace Admin Help article titled “Change a user’s name.”

Use Torii

Rather than changing a user’s name directly inside Google Workspace, you can accomplish this from Torii, a SaaS Management Platform. SMPs centralize management of SaaS apps and subscriptions, letting you orchestrate integrations, automate onboarding/offboarding, review licensing, and more.

Instead of performing the rename manually in Google Workspace each time, Torii lets you automate the update so it runs whenever a specific trigger occurs - for example a new hire, an employee departure, a contract renewal, or another event. Automating repetitive updates like this saves time and reduces the chance of human error.

To update a user name in Google Workspace through Torii, follow these steps:

1. Sign up for Torii

Contact Torii, and request your complimentary two-week proof-of-concept.

2. Connect your Google Workspace account to Torii

After your Torii account is active, add Google Workspace as an integration (this assumes you already have a Google Workspace account). Here are the instructions for the Google Workspace integration.

3. Create a Torii workflow for Google Workspace

In Torii you can build an automated workflow to change a user name in Google Workspace. Open the Workflows tab, define the trigger that should prompt the change, and add an action that updates the user name in Google Workspace. Once this workflow is active, the user name will be updated automatically whenever the trigger fires.

Use Google Workspace’s API

Here you’ll call the Admin SDK Directory API to change a user’s display name or their primary email (username).

Step 1 - pick PATCH or PUT and what you want to change

• Use PATCH (users.patch) for partial updates, like just changing givenName or familyName.
• Use PUT (users.update) if you plan to replace the full user resource.
• Decide if you’re changing the display name (name fields) or the primary email (primaryEmail). The API supports both.

Step 2 - ensure your app has the right credentials and scope

• Use OAuth 2.0 with an admin account, or a service account with domain-wide delegation impersonating an admin.
• Request the write scope: https://www.googleapis.com/auth/admin.directory.user.
• Make sure the access token you send in Authorization is valid and scoped for the admin actions you need.

Step 3 - update the display name (example)

• Endpoint: PATCH https://admin.googleapis.com/admin/directory/v1/users/{userKey}
• userKey can be the user’s primary email or their unique userId.
• JSON body to change first and last name:

{
    "name": {
        "givenName": "Alex",
        "familyName": "River",
        "fullName": "Alex River"
    }
}

Example curl:

curl -X PATCH \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":{"givenName":"Alex","familyName":"River","fullName":"Alex River"}}' \
"https://admin.googleapis.com/admin/directory/v1/users/[email protected]"

Step 4 - change the primary email (username) if needed

To change the username, send a patch with primaryEmail:

{
    "primaryEmail": "[email protected]"
}

Example curl:

curl -X PATCH \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"primaryEmail":"[email protected]"}' \
"https://admin.googleapis.com/admin/directory/v1/users/[email protected]"

Notes:

• The new primary email must not already exist. If it does, the API returns a conflict.
• If you want to preserve the old address as an alias, create an alias via the aliases.insert API for that user before or after the change.

Step 5 - preserve old email as an alias (optional)

• To keep the old address working, create an alias:
• Endpoint: POST https://admin.googleapis.com/admin/directory/v1/users/{userKey}/aliases

Body:

{ "alias": "[email protected]" }

Example curl:

curl -X POST \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"alias":"[email protected]"}' \
"https://admin.googleapis.com/admin/directory/v1/users/[email protected]/aliases"

Step 6 - verify the change

Retrieve the user to confirm:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
"https://admin.googleapis.com/admin/directory/v1/users/[email protected]"

Check the name and primaryEmail fields in the returned JSON.

Step 7 - handle common errors

• 403: insufficient permissions - check scopes and admin impersonation.
• 404: user not found - confirm the userKey is correct.
• 409: primary email already in use - pick a different email or remove the conflicting account.
• The API returns JSON error details; log them and retry after fixing the cause.

Follow the Google Workspace Admin SDK Directory API docs for Users (users.patch, users.update, aliases.insert, users.get) for full parameter lists, example responses, and additional fields you can set.