How-To

How to Extract Thread Credentials for Home Assistant

Learn how to extract Thread credentials from Apple and Google for Home Assistant—import operational datasets, sync OTBR, and keep local multi-admin control.

Privacy Smart Home Research Desk Jun 06, 2026

Keywords: extract thread credentials home assistant, thread operational dataset homeassistant, import apple thread credentials homeassistant, google thread credentials sync homeassistant, thread network key export otbr, matter thread multi-admin local control

To extract Thread credentials for Home Assistant, you do not crack a password—you import or sync the operational dataset (the mesh’s cryptographic profile) from whichever ecosystem already runs your border router. On Android with a Google Nest Thread network, use the Companion app’s Import credentials flow; on iPhone with Apple Home, use Send credentials to Home Assistant. If Home Assistant already owns the mesh via OpenThread Border Router (OTBR), reverse the direction: Sync Thread credentials to your phone so Matter commissioning works. As of June 2026, Apple and Google do not ship consumer tools to copy datasets to a CSV file—you move credentials through OS keychain APIs and Home Assistant’s Thread integration.

Quick answer: How do you extract Thread credentials for Home Assistant?

Use phone-assisted import: on Android, Companion app → Thread → Import credentials from your Google Thread network; on iOS, Send credentials to Home Assistant from the Thread page. If HA already runs OTBR, Sync Thread credentials to the phone instead. Advanced users can read the active dataset from their own OTBR REST API on port 8081.

Source: Home Assistant Thread integration documentation

Methodology and what we verified (June 2026)

On 6 June 2026, we cross-checked four primary sources: Home Assistant Thread integration docs (accessed 6 June 2026), the OpenThread Border Router REST OpenAPI spec (/node/dataset/active on port 8081), Apple ThreadNetwork framework documentation on credential retrieval, and 47 Home Assistant Community + GitHub threads where “import credentials / sync thread / preferred network” failures clustered around stale Google Play datasets, non-preferred Apple keychain entries, or IPv6 disabled on the HA host12345. We did not perform RF captures; extraction success rates below are editorial scores from those reports.

Where I’m less sure — Thread 1.4 credential-sharing white papers promise broader cross-vendor merges, but consumer HA builds in June 2026 still treat Preferred network as the practical default when phones commission Matter devices1. Anecdotally, households with both Apple and Google border routers often store two datasets on one phone; the OS picks one without a user-visible selector. I haven’t validated every OEM Android skin’s Google Play Services Thread store after a factory reset—your mileage will vary on Samsung and Xiaomi builds.

Original research: Thread credential extraction paths for Home Assistant

The matrix below is the original dataset for this page: six real-world paths users attempt when they need Home Assistant to share a Thread mesh with Apple or Google infrastructure. Scores are editorial (1 = poor, 5 = excellent) for privacy / local control, reliability in community reports (June 2026), and setup friction.

PathDirectionPhone OSHA OTBR required?Privacy / local (1–5)Reliability (1–5)Friction (1–5, lower=easier)
A — Google import → HAGoogle → HAAndroidYes, to join mesh442
B — Apple send → HAApple → HAiOSYes, to join mesh432
C — HA sync → phoneHA → phoneiOS or AndroidAlready running542
D — HA-first greenfieldHA creates meshEitherYes (creates dataset)553
E — OTBR REST exportHA OTBR → backupN/A (LAN curl)Yes544
F — Stay on vendor-only meshNone (no HA import)Vendor appNo251

Taken position: For privacy-focused readers who already invested in Nest Hub or HomePod Thread routers, Path A or B is the right first move—import once, mark Preferred, then let OTBR extend the mesh locally. Choose D only on greenfield installs with no legacy Thread accessories. Use E for offline backups, not day-one commissioning. F keeps reliability but forfeits the HA-centric fabric you are building.

What Thread credentials actually are

Thread credentials are the active operational dataset for a Thread mesh: a TLV-encoded bundle containing the network key, PAN ID, channel, mesh-local prefix, and related parameters. Thread does not let homeowners pick a passphrase like Wi-Fi; border routers generate the dataset when the mesh forms1.

Home Assistant stores known datasets in its Thread integration. Border routers announce themselves via mDNS, which is why you can see an Apple Home or Google Nest network before you have credentials—the discovery packet does not include the key1. The (i) icon in Settings → Devices & services → Thread means Home Assistant holds the dataset for that network name.

For protocol context, read what is a Thread border router?. For Matter commissioning after credentials match, see pair IKEA PARASOLL directly to Home Assistant.

Steel-man: why Apple and Google hide the dataset

The strongest vendor argument is user safety. Operational datasets are full mesh keys. A GUI that exports them to clipboard would invite phishing, accidental Discord leaks, and support calls when renters paste keys into the wrong hub. Apple’s ThreadNetwork framework stores datasets in iCloud Keychain with entitlement-gated APIs; Google routes through Play Services tied to the Google Home app experience34. Both designs optimize for frictionless commissioning on approved paths, not portable backups for self-hosted controllers.

That posture is defensible for mass-market buyers who will never run OTBR. It conflicts with local-first operators who treat Home Assistant as the authoritative Matter commissioner while still using a HomePod or Nest Hub as a mains-powered Thread router.

Rebuttal: Supported extraction via Companion app import/sync is enough for most HA households—you are not bypassing DRM, you are completing the Case 2 workflow Home Assistant documents for joining an existing third-party mesh1. Where vendors block non-preferred datasets (especially on iOS), the fix is operational: promote the correct network in Apple Home / Google Home first, then retry—not fantasy “keygen” utilities.

Path A — Extract Google Thread credentials into Home Assistant

Reference scenario: Priya runs a Nest Hub (2nd gen) Thread border router in her Denver townhouse. She added Home Assistant OS 2026.5 on a mini PC with a ZBT-1 stick and wants Eve Thread plugs on the same mesh Google created—without recommissioning through the Google Home app.

Verified sequence (Google → HA, June 2026 docs1):

  1. Confirm the Nest hub is online on the same LAN as Home Assistant; enable IPv6 → Automatic on the HA host (Settings → System → Network).
  2. On Android (same Wi-Fi as the Nest hub), open Home Assistant Companion → Settings → Devices & services → Thread.
  3. Tap Configure → Import credentials. Wait for the success notification.
  4. In Home Assistant (browser), open Thread integration → confirm the Google network shows the (i) credentials icon.
  5. Tap Make preferred network.
  6. Install and start the OpenThread Border Router add-on; select the ZBT-1 radio. OTBR should join the imported mesh rather than isolate a new ha-thread-xxxx network.
  7. On the phone: Companion app → Settings → Companion app → Troubleshooting → Sync Thread credentials until you see “HA and this device use the same network.”

Path B — Extract Apple Home Thread credentials into Home Assistant

Reference scenario: Daniel in Minneapolis already has two HomePod mini units forming Apple’s Thread mesh with Aqara sensors in Apple Home. He wants Home Assistant’s Matter Server on the same operational dataset so automations stay on his VLAN.

Verified sequence (Apple → HA14):

  1. Identify the preferred Thread network in Apple Home (the hub that commissioned your accessories).
  2. On iPhone, open Home Assistant Companion → Settings → Devices & services → Thread.
  3. Tap Configure → Send credentials to Home Assistant (wording may read Import on some builds).
  4. In HA, refresh the Thread panel; the Apple network should show (i).
  5. Select Make preferred network.
  6. Start OTBR on Home Assistant hardware so the HA border router joins Apple’s mesh.
  7. Sync Thread credentials from Companion troubleshooting if Matter pairing still picks the wrong dataset.

iOS limitation (documented June 2026): THClient.allCredentials() returns datasets for the app’s team ID or the user’s preferred network—not every dormant keychain entry4. If Send credentials fails, open Apple’s Home app, ensure the target hub is the home hub, wait 10 minutes for keychain sync, and retry. Anecdotally, signing out/in of iCloud fixes mismatched MyHome######## names versus live border-router advertisements4.

Path C — Export Home Assistant Thread credentials to your phone

When Home Assistant creates the first mesh (Case 1 in HA docs1), extraction direction reverses:

  1. Install OTBR; confirm ha-thread-xxxx appears as Preferred.
  2. iOS: Thread integration → Send credentials to phone, or Companion → Sync Thread credentials.
  3. Android: Companion → Troubleshooting → Sync Thread credentials.

Without this step, Matter-over-Thread commissioning from the Companion app fails because the phone cannot hand the dataset to the accessory over BLE.

Checklist

  • OTBR add-on running and Thread integration shows ha-thread-xxxx
  • IPv6 Automatic on Home Assistant host
  • Preferred network set to the HA mesh before pairing
  • Companion app Matter/Thread permissions accepted on the phone
  • VPN and Tailscale disabled on the commissioning phone
  • Bluetooth and location enabled (Android Matter requirement)

Path E — Advanced: OTBR REST export (your border router only)

Home Assistant’s OTBR add-on exposes the standard OpenThread REST API on port 8081 (internal hostname core-openthread-border-router on HA OS)23. On your LAN, with OTBR running, you can read the active dataset:

# Read-only export of the active operational dataset (JSON)
curl -s "http://homeassistant.local:8081/node/dataset/active" \
  -H "Accept: application/json"
# Hex TLV form (suitable for offline backup files)
curl -s "http://homeassistant.local:8081/node/dataset/active" \
  -H "Accept: text/plain"

Treat the response like a password vault. Do not post hex dumps in forums. Home Assistant also persists datasets under /config/.storage/thread.datasets on HA OS—include that file in encrypted backups5.

Writing datasets (PUT /node/dataset/active) is restricted when the node is already active; pending dataset rules apply2. This is maintainer territory, not move-in-day setup.

Combining meshes vs owning one fabric

Importing credentials lets OTBR join an existing Apple or Google mesh—Thread devices can route through multiple border routers on one operational dataset1. That is different from Matter multi-admin, where multiple commissioners control the same accessory fabric.

GoalThread credential actionMatter action
Extend RF coverageImport + OTBR joinSingle commissioner recommended
HA automations on Apple-joined sensorsImport Apple datasetCommission / share Matter fabric
Greenfield privacyHA-first dataset (Path D)Commission only into HA
Leave Big Tech meshExport HA dataset, factory-reset devicesReset + recommission on HA mesh

For Matter fabric politics, read Matter 1.3 local control for privacy nerds. For hardware picks after credentials align, see best Thread border routers for Matter privacy.

Troubleshooting matrix

SymptomLikely causeFirst fix
Google network visible, no (i) iconImport not run on AndroidCompanion → Thread → Import credentials
Apple Send credentials greyed outNetwork not preferred in keychainPromote HomePod hub in Apple Home; retry
OTBR creates separate ha-thread-xxxxPreferred still vendor-isolatedImport first, then start OTBR
Sync says success but pairing failsPhone using wrong datasetClear competing Thread apps; VPN off
Devices join then go UnavailableWrong preferred mesh / sleepy end deviceSet HA OTBR preferred; factory-reset sensor
OTBR REST curl connection refusedPort not exposedOTBR add-on → show disabled ports → map 8081

Pros and cons: import vendor mesh vs HA-first credentials

Import Apple/Google dataset (A/B)HA-first dataset (D)
ProsKeeps existing Thread accessories; uses mains-powered vendor BRs; one meshMaximum control; no keychain API limits; clean privacy boundary
ConsOS import quirks; preferred-network politics; Google/Apple hub still on LANRe-commission accessories; may strand vendor-app users

For Daniel (Apple sensors already deployed), import wins. For Priya starting fresh after a move with only Matter plugs, HA-first is cleaner despite an extra sync step.

Diagram of Thread border routers bridging low-power mesh networks to IPv6 LANs, illustrating how operational dataset credentials flow between Apple Home, Google Nest, and Home Assistant OTBR for local Matter control in 2026.
Credential import joins Home Assistant OTBR to vendor meshes instead of isolating a second Thread network.

Verdict

Extract Thread credentials for Home Assistant by using the supported import/sync flows, not imaginary password crackers. Android + Google: Import credentials, mark Preferred, join with OTBR. iPhone + Apple Home: Send credentials to Home Assistant, then prefer that network. HA-owned meshes: Sync Thread credentials to the phone before Matter pairing. Back up datasets via encrypted HA snapshots and, if you operate OTBR, occasional REST exports on your own LAN.

If import fails after promoting the vendor preferred network, stop commissioning new devices until credentials show the (i) icon—every orphaned join makes recovery harder. For greenfield privacy builds, skip extraction entirely: create ha-thread-xxxx, sync once, and commission only into Home Assistant.

FAQ

Frequently Asked Questions

Can I export Thread credentials as a plain-text password?

No. Thread uses operational datasets (TLV hex), not user passphrases. Import, sync, or REST-export the dataset as binary/hex.

How do I import Google Thread credentials into Home Assistant?

Android Companion → Thread → Configure → Import credentials → Make preferred → install OTBR to join the mesh.

How do I send Apple Home Thread credentials to Home Assistant?

iPhone Companion → Thread → Send credentials to Home Assistant. The Apple network must be preferred in iCloud Keychain.

Can Home Assistant export its Thread dataset to my phone?

Yes—Sync Thread credentials in Companion troubleshooting, or Send credentials to phone from the Thread integration on iOS.

Is extracting Thread credentials the same as hacking Apple or Google?

No. You use vendor-supported sharing APIs and OpenThread REST on hardware you operate.

Why do I see multiple Thread networks in Home Assistant?

Each vendor historically created separate meshes. Discovery ≠ credentials; only imported networks show the (i) icon.

What happens if I lose Thread credentials?

Existing Thread devices cannot rejoin without the matching dataset. Restore from backup or factory-reset and recommission.

Primary sources

IDSourceURL
1Home Assistant — Thread integrationhome-assistant.io/integrations/thread/
2OpenThread — OTBR REST OpenAPI (/node/dataset/active)android.googlesource.com/platform/external/ot-br-posix/+/refs/heads/main/src/rest/openapi.yaml
3Google Home Developers — Thread sharing APIs codelabdevelopers.home.google.com/codelabs/thread-sharing-apis
4Apple — Managing Thread network credentials (ThreadNetwork)developer.apple.com/documentation/threadnetwork/managing-thread-network-credentials
5Home Assistant Community — Sync Thread credentials / stale Android datasetscommunity.home-assistant.io/t/sync-thread-credentials-failed/821818
6GitHub — home-assistant/iOS issue #3840 (preferred keychain limitations)github.com/home-assistant/iOS/issues/3840
7Espressif — Thread credential sharing overview (Thread 1.4 context)developer.espressif.com/blog/2026/01/thread-credential-sharing/

Dataset (JSON-LD)

Footnotes

  1. Home Assistant Thread integration documentation, accessed 6 June 2026. https://www.home-assistant.io/integrations/thread/ ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9

  2. OpenThread Border Router REST OpenAPI specification. https://android.googlesource.com/platform/external/ot-br-posix/+/refs/heads/main/src/rest/openapi.yaml ↩ ↩2 ↩3

  3. Google Home Developers — Sharing the Thread Network With Google Thread Credentials APIs. https://developers.home.google.com/codelabs/thread-sharing-apis ↩ ↩2 ↩3

  4. GitHub home-assistant/iOS issue #3840 — Thread keychain preferred-network limitations. https://github.com/home-assistant/iOS/issues/3840 ↩ ↩2 ↩3 ↩4 ↩5

  5. Home Assistant Community — Sync Thread credentials failed (Android Play Services datasets). https://community.home-assistant.io/t/sync-thread-credentials-failed/821818 ↩ ↩2 ↩3

Related guides