Supporting Google Account username change in your app

As of March 31, users in the US can now update their Google Account username while keeping their account, inbox, and data fully intact. If your platform uses Sign in with Google or identifies users by email, this post explains how this update affects your integration and any steps you may need to take.

Many users have old email addresses that no longer reflect who they are—whether due to a name change, a shift in professional identity, or simply a username that they have outgrown.

With this update, when a user changes their username, their original email address is retained as an alternative linked to the same account. Both emails point to the same inbox. Users can continue to sign in, send, and receive email using either. While this capability has been available to business Workspace users, we're now expanding it to consumer Google Accounts with a @gmail.com address.

What it means for your platform

How this feature affects your users depends on how they authenticate with your platform and how your platform identifies them.

Sign in with Google users, identified by subject ID

If your platform already uses subject ID as the primary account identifier, no action is needed. The subject ID is stable and will not change, regardless of any changes made to the email address.

Sign in with Google users, identified by email address

If your platform uses Sign in with Google, and maps user accounts based off of the email address from the ID token, some users may experience disruption after changing their username.

• If an OAuth grant from before the username change remains active, Google will continue to provide the old email address to maintain continuity. The user authentication experience should typically remain uninterrupted.

• However, if an OAuth grant was revoked by the user, Google will provide the new email address instead on subsequent sign in. This may cause your platform to fail to recognize the user, potentially resulting in duplicate accounts and loss of access to existing data.

As a best practice, we recommend migrating to subject ID as your primary user identifier. See the recommendations section below.

Manual account and password users

For users who sign in with email and password, the sign-in experience will be unaffected. The user’s old email address remains active, so they can continue signing in as normal. Since a user originally created the account on your platform using an email address and password, your platform has no subject ID on file; it only knows the email address.

• Risk of duplication: If the user later attempts to use Sign in with Google with a new email address, your platform will be unable to link this new Google identity to an existing account, which could create a duplicate account.

To prevent this from occurring, allow users to update the email address associated with their account on your platform. This allows users to seamlessly sign in to their existing account using Sign in with Google, alongside email and password.

A note on passkeys

For users who use passkeys to sign into your platform, this feature will not impact their sign-in experience.

Our Recommendations

To ensure a smooth transition for your users, we recommend following these three steps:

• Use subject ID as your primary user identifier. Subject ID (sub) is the most reliable identifier for a Google user and remains unchanged even if a user updates their email address. We strongly recommend using it as the primary key for any user account authenticated via Sign in with Google. You can find more technical details on Subject ID in our implementation best practices.

• Provide email-based account recovery. If adopting the subject ID is not immediately feasible, offering email-based account recovery is essential. Since Google retains the old email address as an alias, recovery messages sent to the original address will still reach the user.

• Enable email updates. For users who signed up to your platform with traditional email and password accounts, allow them to update their contact information within your platform settings to prevent sign-in issues.

We encourage you to review your current authentication options and implement these updates to maintain a seamless user experience.

A great experience for your users

With these improvements, we’re making users’ experience simpler and safer, so users can easily stay engaged on your platform. If you have any questions, visit developers.google.com.