Renaming your SharePoint domain

The SharePoint and OneDrive URLs come from the tenant's original onmicrosoft.com name chosen at sign-up – which may carry a legal-form suffix or a typo nobody noticed. Adding a custom domain doesn't change them, and neither does making a new onmicrosoft.com domain the fallback. The only way is the tenant rename.

Steps 0 to 3 come from a real rename scheduled in November 2026 on a freshly built tenant: two visible sites, no content yet, nobody using it. Step 4 follows Microsoft's docs – the run hadn't completed at the time of writing. That is the cheapest moment there will ever be – on a tenant in use, read Microsoft's limitations table first; hub sites, Power Automate, Power BI, Teams tabs and anything with absolute URLs need follow-up work.

Before you start

• It's one-way. You can't rename back to the original name, you get at most two renames in the tenant's lifetime, and a second one can't be scheduled within 30 days of the previous one completing. Get the name signed off by the tenant owner before step 2.
• Deleted sites are lost for good. Check SharePoint admin center → Sites → Deleted sites and restore anything worth keeping – sites deleted before the rename can't be restored after it.
• Freeze licensing and admin roles. Microsoft says purchases or changes to licences and storage, and creating or updating admin roles, don't take effect during the rename. If the customer is about to buy licences, either buy them before the scheduled start or after it finishes.
• Old URLs keep working for a year through a redirect, then stop.
• E-mail addresses and sign-in names don't change – only SharePoint and OneDrive URLs.

Step 0: check the new name is free

Two quick probes, no sign-in needed:

Resolve-DnsName contoso.sharepoint.com
Invoke-WebRequest "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration" -SkipHttpErrorCheck | Select-Object StatusCode

• contoso.sharepoint.com doesn't resolve – the name is most likely free. (Microsoft's own check is the browser: a 404 means probably free, a sign-in page means taken.)
• The OpenID endpoint returns 400 for an onmicrosoft.com name no tenant owns and 200 for one that exists (try it on your current name to see the 200). You need both names, because step 1 claims the matching onmicrosoft.com domain.

(-SkipHttpErrorCheck is PowerShell 7. In Windows PowerShell 5.1 drop it – a 400 then throws a WebException and a 200 returns normally. Resolve-DnsName is Windows-only.)

The new name can't contain a hyphen or special characters, is limited to 48 characters, and can't be a name your tenant used before.

If another customer has the name, Microsoft can't tell you who or contact them for you. Pick another.

Step 1: add the matching onmicrosoft.com domain

1. Microsoft 365 admin center → Settings → Domains.
2. Select your current contosoltd.onmicrosoft.com (Default) domain. Don't use the Add domain button at the top of the page – it adds a custom domain, not an onmicrosoft.com one.
3. In About this domain, select Add onmicrosoft domain, type contoso, select Add domain.
4. Wait until the new domain shows Healthy.
5. Do not select Make fallback domain on it.

This needs the Domain Name Administrator role (Global Administrator includes it). Check the spelling twice: a tenant can have at most five onmicrosoft.com domains and they can't be deleted.

Step 2: schedule the rename

On Windows (the module doesn't run on a Mac), in Windows PowerShell 5.1, signed in as at least a SharePoint Administrator:

Uninstall-Module Microsoft.Online.SharePoint.PowerShell -AllVersions -Force -ErrorAction SilentlyContinue
Install-Module -Name Microsoft.Online.SharePoint.PowerShell -Scope CurrentUser -Force
Connect-SPOService -Url "https://contosoltd-admin.sharepoint.com"

If the sign-in fails with Unable to load DLL 'msalruntime' followed by No valid OAuth 2.0 authentication session exists, the Windows sign-in broker couldn't start. Sign in through the browser instead – pick the admin account of the tenant being renamed, not whatever account the browser offers first:

Connect-SPOService -Url "https://contosoltd-admin.sharepoint.com" -UseSystemBrowser $true

Dry run first:

Start-SPOTenantRename -DomainName "contoso" -ScheduledDateTime "2026-11-14T08:00:00" -WhatIf

The output looks alarming but is the normal -WhatIf result – nothing was scheduled:

What if: Performing the operation "Start-SPOTenantRename."
You have aborted the rename operation.

The scheduled time is the local time of the machine you run it on, and it must be at least 24 hours and at most 30 days ahead. Typing a time a few hours away fails after you confirm, with error code -772 (the message is localized; on a Czech system it read Error Code: -772,Plánované datum a čas musí být v budoucnosti 24 hodin. – the scheduled date and time must be 24 hours in the future). Computing the time avoids both the error and any doubt about which clock counts:

$when = (Get-Date).AddHours(25).ToString("s"); $when
Start-SPOTenantRename -DomainName "contoso" -ScheduledDateTime $when

Answer Y to the confirmation. Success prints a RenameJobID. Until the start time you can still cancel – the -Reason is mandatory:

Stop-SPOTenantRename -Reason "Rescheduling"

Step 3: check what got scheduled

Get-SPOTenantRenameStatus

RenameJobId     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (redacted)
Status          : Queued
Requested at    : 11/10/2026 5:30:54 PM (UTC)
Requested by    : admin@contosoltd.onmicrosoft.com
Scheduled at    : 11/11/2026 6:30:47 PM (UTC)
New domain name : contoso
Total sites     : 5

In progress       : 0
Renamed           : 0
Attention required: 0

• Times are shown in UTC – our 19:30 Central European time appears as 6:30 PM. Check the offset matches what you meant.
• Total sites counted 5 although Active sites in the admin center listed only two. The rename counts sites that list doesn't show, so don't read a mismatch as an error (we didn't break the five down).
• Attention required is the number to watch. If more than 10 % of sites fail to rename, the whole operation suspends and needs a support request to resume.

Once it starts, sites still waiting for their turn are briefly inaccessible, and creating new sites, teams or private channels is blocked until it finishes. Microsoft puts the duration at hours to days depending on the number of sites. Schedule it for a quiet evening or weekend and tell users.

When you're done, Disconnect-SPOService. Don't plan UPN changes until the rename completes. Once it has started, check progress from a new PowerShell window; if Get-SPOTenantRenameStatus returns access denied, connect to the new admin URL (https://contoso-admin.sharepoint.com).

A status of all zeros right after scheduling (a zero RenameJobId) is Microsoft's documented symptom of an outdated module – that's why the install step removes old versions first.

Step 4: after it completes

• Get-SPOTenantRenameStatus shows every site under Renamed and Attention required: 0. For the per-site list, Get-SPOSiteRenameState -ParentOperationID <RenameJobID>.
• Open https://contoso.sharepoint.com and the admin center at https://contoso-admin.sharepoint.com, and try one of the old URLs to see the redirect.
• On a tenant that was already in use, walk the limitations table – re-register hub sites, fix absolute URLs in navigation, flows and apps, and republish isolated SPFx solutions.

Notes

• The fallback domain stays contosoltd.onmicrosoft.com. That's fine: sign-in names come from the users' UPNs, which normally use your custom domain, not the fallback.
• The standard rename covers tenants with up to 10,000 sites; multi-geo, government clouds and vanity domains can't be renamed at all.
• Microsoft's docs: Errors when renaming, Change your SharePoint domain name, Add an onmicrosoft.com domain, Connect-SPOService.