What Thread credentials are and why you need them in Home Assistant

Thread credentials are the security keys that let your Thread devices talk to each other and to Home Assistant. When you set up a Thread network — whether through an Apple Home Hub, Google Home device, or a dedicated Thread border router — that network generates a unique credential file. Home Assistant needs this file to join the network and communicate with your Thread devices.

Without importing the credentials, Home Assistant cannot see or control any Thread devices on your network, even if they are physically nearby. The credential file acts as a password that proves Home Assistant is allowed to participate in that specific Thread network.

Key Takeaways

  • Thread credentials are security files generated when you create a Thread network, and Home Assistant needs them to join that network.
  • The credential file usually comes from whichever device created your Thread network — Apple Home, Google Home, or a dedicated border router.
  • Home Assistant imports credentials through the Settings menu under Devices and Services, then Thread, then the Import Credentials button.
  • The import process takes a few minutes and Home Assistant will restart automatically once the credentials are loaded.
  • If you do not have the credential file, you may need to factory reset your Thread border router or create a new Thread network from scratch.

Where to find your Thread credential file

The location of your credential file depends on which device created your Thread network. If you use Apple Home, the credentials live on your iPhone, iPad, or Mac — you export them through the Home app. If you use Google Home, you export them through the Google Home app on Android or iOS. If you have a dedicated Thread border router like the Nanoleaf Essentials Thread Border Router or Aqara Hub M2, check that device's own app or web interface.

The credential file is usually a small text file with a name like thread-credentials.json or similar. Some apps let you email it to yourself or save it to cloud storage; others require you to connect the device to a computer and copy the file directly. Check your device's manual or support page if you are unsure how to export it.

If you have lost the credential file and cannot export it again, you will need to factory reset your Thread border router and create a new Thread network. This means your existing Thread devices will need to rejoin the new network, which usually takes a few minutes per device.

How to import credentials through Home Assistant Settings

Open Home Assistant and go to Settings in the left sidebar. Select Devices and Services, then look for the Thread card. If you do not see a Thread card, your Home Assistant installation may not have Thread support enabled yet — check that you are running Home Assistant 2023.3 or later.

Click the Import Credentials button on the Thread card. Home Assistant will open a file browser. Navigate to the credential file you exported from your Thread network creator (Apple Home, Google Home, or your border router app) and select it. Home Assistant will read the file and begin importing the credentials.

The import process usually takes one to three minutes. Home Assistant may restart automatically during this time — this is normal and expected. Once the restart is complete, check the Thread card again. You should see a message confirming that credentials have been imported, and the card may show details about your Thread network like the network name and the number of devices connected.

What happens after you import credentials

Once credentials are imported, Home Assistant becomes a Thread device on your network. It will not automatically appear as a border router unless you have a compatible radio — most standard Home Assistant installations join as a regular Thread device. This is fine for controlling Thread devices; you do not need Home Assistant to be a border router.

Your existing Thread devices should remain connected to their current network. New Thread devices you add will be able to see Home Assistant and use it as a path to reach other devices on the network. If you have multiple border routers (for example, an Apple Home Hub and a Google Home device), Home Assistant will join whichever network the credential file represents.

Home Assistant will now show Thread devices in the Devices list as they connect. You can create automations, scenes, and dashboards that control these devices just like any other Home Assistant integration.

Troubleshooting import errors

If Home Assistant rejects the credential file, the most common cause is that the file is corrupted or in the wrong format. Try exporting the credentials again from your Thread network creator and re-importing. Make sure you are exporting the actual credential file, not a screenshot or backup of your entire home setup.

If the import appears to succeed but Home Assistant does not show any Thread devices afterward, check that your Thread devices are powered on and within range of a border router. Thread devices need a clear path to at least one border router to communicate with Home Assistant. If a device is too far away or blocked by interference, it may not appear even after credentials are imported.

If you see an error message about "invalid credentials" or "network mismatch," the credential file may be from a different Thread network than the one your devices are on. This can happen if you have multiple Thread networks in your home. Export credentials from the correct network creator and try again.

When you need to re-import or update credentials

You only need to import credentials once per Thread network. If you add new Thread devices to the same network, you do not need to re-import anything — Home Assistant will see them automatically once they join.

If you create a brand new Thread network (for example, by factory resetting your border router), you will need to export the new credentials and import them into Home Assistant again. The old import will no longer work because the network keys have changed.

If you switch from one Thread network to another — say, from an Apple Home network to a Google Home network — you will need to import the new credentials. Home Assistant can only be on one Thread network at a time.

Frequently Asked Questions

Can I import credentials from multiple Thread networks into one Home Assistant?

No. Home Assistant can only join one Thread network at a time. If you have multiple Thread networks in your home, you will need to choose which one to import credentials from. All your Thread devices should ideally be on the same network anyway, since that is how they communicate with each other.

What if I do not have a Thread border router yet?

You cannot import credentials until a Thread network exists. You need at least one border router — an Apple Home Hub, Google Home device, or dedicated router like Nanoleaf or Aqara — to create the network first. Once that device creates the network, you can export credentials from it and import them into Home Assistant.

Will importing Thread credentials affect my existing smart home automations?

No. Importing Thread credentials only adds Thread support to Home Assistant. Your existing automations, scenes, and integrations will continue to work unchanged. Thread devices will appear as new devices in Home Assistant, but they do not interfere with anything already set up.

Do I need to restart Home Assistant after importing credentials?

Home Assistant usually restarts automatically during the import process. If it does not, you can manually restart it through Settings > System > Restart Home Assistant. The restart ensures the Thread integration loads properly with the new credentials.

What if the credential file is password-protected?

Some Thread network creators may encrypt the credential file. If that is the case, the app that exported the file should have given you a password or asked you to set one. You will need that password to import the file into Home Assistant. If you have lost the password, you will need to export the credentials again and set a new password, or factory reset the border router and create a new network.