How to update email addresses when switching to a new domain

Overview

This is the admin runbook for moving your LaunchDarkly account to a new email domain. It covers two scenarios:

• An email domain change with no SSO changes.

• A combined SSO provider swap and email domain change (see section 4).

Solution

1. Choose your path by plan tier

The right path depends on your LaunchDarkly plan. SCIM is Enterprise-only.

• Enterprise or above - SCIM (section 2). Update emails in your IdP and SCIM syncs the change.

• Not Enterprise - Most members self-serve. OAuth-linked members need admin delete-and-recreate. Both covered in section 3.

2. Execute: SCIM (Enterprise)

1. Configure SCIM. Follow Enable SCIM provisioning.

2. Update each member's email in your IdP.

3. SCIM syncs the change to LaunchDarkly. No member action needed.

SCIM updates skip the member-facing email verification step.

3. Execute: Self-service (Not Enterprise)

Before you start

If SAML SSO is enforced on your account

When SSO is enforced, the email field on member profiles is locked. Put your SAML config into test-drive mode for the rename window:

1. In Settings > Security > SAML, switch from enforced to test-drive (enabled, not required).

2. Members update their emails:

   • 2a. Non-OAuth-linked members self-serve (see "Members update their emails" below).

   • 2b. OAuth-linked members go through delete-and-recreate (see "Members update their emails" below).

3. Turn off test-drive mode and re-enforce SSO once everyone's done.

During test-drive mode, both email/password and SSO sign-in remain functional, so members are not locked out. There is no deadline for completion.

Warning: do not re-enforce SSO until every non-OAuth-linked member has updated their email. Re-enforcing relocks the email field, and anyone who has not renamed will be stuck.

Note: personal access tokens considerations. Personal access tokens belong to individual members. They are preserved when a member updates their email in place, and they are lost when a member is removed. If your team relies on personal access tokens for CI pipelines, scripts, or integrations, list them ahead of the migration window so you know what to regenerate.

On Enterprise or above, consider switching automation to service tokens instead. Service tokens belong to the organization, not to an individual member, so they survive member changes. See Creating API access tokens. Service tokens are not available on Foundation or Pro.

Communicate with your team

Let members know what's coming before the rename window. Use whatever channels your team already uses. Some options:

• In-app announcement banner at Settings > General > Announcement banner, with a scheduled active period. See Organization announcements.

• Email to your team.

• Slack or other chat in your team's channel.

Whatever you use, point members at How to change your LaunchDarkly email address for the steps, and tell them to contact the account admin if they see "You cannot change your email address as it is connected to…".

Example copy (adapt for your channel):

We're migrating to a new email domain. Please update your LaunchDarkly email before <date>. Reference https://support.launchdarkly.com/hc/en-us/articles/52238902875931-How-to-change-your-LaunchDarkly-email-address for instructions. If you encounter "You cannot change your email address as it is connected to Google," contact your admin.

Choose your migration strategy

Members update their emails

Non-OAuth-linked members. Share How to change your LaunchDarkly email address with them and they handle the rest. Roles, teams, audit-log history, and personal access tokens are preserved. Integrations and webhooks keep working — SDK keys and environment API tokens are scoped to the account, not to a member.

Note: emails are case-sensitive in some contexts. Use the exact casing your IdP will send, or you may end up with duplicate accounts.

OAuth-linked members. Any member who's used a Sign in with… OAuth button is OAuth-linked. Their email field is locked, and there's no self-serve unlink. You'll need to delete and recreate these members.

To find them, ask each member to load https://app.launchdarkly.com/profile . A greyed-out email field with "You cannot change your email address as it is connected to…" means they're OAuth-linked. List them up front so you can batch the work.

Delete-and-recreate loses the member's roles, teams, and personal access tokens — plan to re-grant. For the full procedure, see Error: "You cannot change your email address as it is connected to…" when changing email address.

Bulk re-provision (when self-service isn't feasible)

If per-member self-service isn't practical, remove and re-invite members in bulk via the UI or API. Roles, teams, and personal access tokens are lost and must be re-issued.

4. If you're also migrating SSO providers: combined workflow

Use this section if you're switching IdPs (for example, Google SSO to Okta SSO) and changing email domains at the same time.

Choose your migration strategy

Two strategies. Pick before you start, based on what you want to keep (roles, teams, personal access tokens, audit-log history) and how fast you need to move.

Strategy A: Preserve existing accounts. Test-drive the new IdP, let members update their emails, then enforce SSO. Pick this when role, team, personal-access-token, or clean audit-log continuity matters.

While the new IdP is in test-drive:

• Non-OAuth-linked members can update their emails; OAuth-linked members stay locked.

• Members with old- and new-domain emails coexist on the same account.

• Both email/password and SSO sign-in keep working.

• No deadline.

Strategy B: Re-provision via the new IdP. Remove members and let the new IdP create fresh accounts (automatable via SCIM on Enterprise). Faster, but personal access tokens are lost and audit history splits between old and new records.

Side-by-side comparison

If continuity matters, preserve. If you need speed and can lose personal access tokens, re-provision.

Note: OAuth-linked members always go through delete-and-recreate (see section 3), regardless of strategy. Their personal access tokens are lost as a consequence.

Ordering of operations (preserve-accounts strategy)

Order matters — out-of-sequence steps lock people out.

1. Identify OAuth-linked members. See section 3.

2. Set up the new IdP in test-drive mode. See Change SSO providers.

3. Remind members of the schedule. Reinforce the announcement from section 3 as the window approaches.

4. Members update their emails. Non-OAuth-linked self-serve; OAuth-linked delete-and-recreate. Both via section 3.

5. Verify all renames complete. Track off-platform.

6. Enforce SSO with the new provider. See warning below.

Strong warning: enforce SSO only after all renames complete

When SSO is enforced, the email field locks. Anyone who hasn't renamed will be stuck and need admin intervention. Don't enforce until everyone's done.