How to Import Thread Credentials in Home Assistant

Thread is one of the newer networking protocols making its way into smart home setups, and Home Assistant has built meaningful support for it. If you've recently added a Thread-based device — or you're migrating from another platform — you may need to import Thread credentials to get everything talking properly. Here's what that process actually involves and what you need to know before you start.

What Are Thread Credentials and Why Do They Matter?

Thread is a low-power, mesh networking protocol designed specifically for smart home devices. It operates on the 802.15.4 radio standard and doesn't connect directly to your Wi-Fi router. Instead, it relies on a Thread Border Router — a device that bridges your Thread mesh network to your regular IP network.

Thread credentials are essentially the network key and configuration data that define a specific Thread mesh network. They include:

• The Network Name
• The Extended PAN ID (Personal Area Network identifier)
• The Network Key (previously called the Master Key)
• The Channel the network operates on
• The Pan ID

Every Thread device that joins a network needs these credentials. When you import credentials into Home Assistant, you're telling it which Thread network to use — or helping it take ownership of an existing one. This matters most when you're consolidating devices from Apple Home, Google Home, or a previous Thread Border Router into Home Assistant's control.

When You Actually Need to Import Thread Credentials

Not everyone needs to do this. There are a few common scenarios where importing becomes necessary:

Migrating from another platform — If your Thread devices were previously running on an Apple HomePod mini, Apple TV 4K, or a Google Nest Hub, those devices created their own Thread networks with their own credentials. To manage those devices natively in Home Assistant, you may need to import those credentials so your Home Assistant border router can participate in — or take over — that same network.

Running multiple Thread networks — In some setups, multiple Thread networks exist in the same home. Importing credentials helps Home Assistant join a specific existing network rather than creating a new one.

Device re-commissioning — Some Thread devices don't re-commission easily to a new network. Keeping credentials consistent avoids the need to factory reset and re-pair devices.

What You Need Before You Start

Before attempting to import Thread credentials, confirm you have:

• Home Assistant OS or Supervised install (Thread support is more limited on Container or Core installs)
• A compatible Thread Border Router — this is typically a Home Assistant Connect ZBT-1, Yellow, or SkyConnect running the OpenThread Border Router (OTBR) add-on, or a compatible third-party border router
• The OpenThread Border Router (OTBR) add-on installed and running
• The Thread integration active in Home Assistant
• Access to your existing Thread network credentials (from Apple, Google, or another source)

🔧 The OTBR add-on is what actually handles Thread networking. Without it configured, credential import has nowhere to go.

How to Import Thread Credentials in Home Assistant

Step 1 — Access the Thread Integration

Navigate to Settings → Devices & Services → Thread. If you don't see it listed, you may need to add it via Add Integration and search for Thread.

Step 2 — Open the Thread Network Panel

Inside the Thread integration, you'll see your active Thread networks listed (if any). Home Assistant may have already created a default network when your border router was set up.

Step 3 — Import Credentials

Select the three-dot menu (⋮) next to your border router or the network panel, then choose Import credentials (the exact label may vary slightly depending on your Home Assistant version).

You'll be prompted to enter:

These values come from your existing Thread platform. On Apple devices, you can retrieve them using the iPhone's Home app or via the Apple Thread credentials transfer (which Home Assistant can pull automatically on newer versions through Matter/Thread commissioning flows). On Google, credentials are managed through the Google Home app and may require a developer API approach.

Step 4 — Confirm and Apply

Once entered, confirm the import. Your border router should now be operating on the same Thread network as your existing devices. Home Assistant may take a moment to re-establish the mesh.

Where Things Get More Complicated 🔍

The process described above is straightforward in isolation, but real-world setups introduce variables that change the experience significantly:

Version differences — Home Assistant updates its Thread tooling fairly actively. The exact menu paths, what's exposed in the UI, and how automatic credential syncing works can differ between versions.

Border router hardware — Not all border routers hand off credentials in the same way. Some support full dataset import; others are more limited in what they expose.

Platform cooperation — Apple's credential sharing via Matter is more automated in recent HA versions. Google's Thread credential access is less standardized and may require additional steps or API tooling.

Multiple border routers — If you have more than one Thread border router in your home (which is actually good for mesh redundancy), keeping their credentials synchronized is its own consideration.

Device compatibility — Some older Thread devices may not re-join a new border router automatically even when credentials match, especially if they were originally commissioned through a different controller.

Your specific combination of Home Assistant version, border router hardware, previous platform, and device roster determines how smooth or involved this process turns out to be for you.