How to Connect Home Assistant

Connect your own Home Assistant so your team can see and control the devices it manages. The platform reaches your instance over the internet by its domain name, so it must answer over HTTPS.

Before you start

• You need the Manage IoT Connections right.
• Home Assistant must be version 2024.1 or later.
• Home Assistant must be reachable from outside by a domain name (for example https://home.example.com, or your Home Assistant Cloud address). IP addresses and plain HTTP are not accepted, and only ports 443 and 8123 are allowed.
• New Home Assistant OS installations answer on port 80 without HTTPS. Set up HTTPS first, for example with Home Assistant Cloud.
• In Home Assistant, create a user for this connection under Settings → People. Commands sent from here are recorded under that user.

Connect it

1. Go to Settings → Devices (IoT) → Connections and choose Add connection.
2. In Add a connection, choose Home Assistant (under Smart home).
3. In Name this connection, enter the name people will see.
4. Enter your Home Assistant address.
5. Choose Sign in. Home Assistant opens in the same tab. Sign in as the user you created and approve. You come back to the Connections tab.

If you would rather not sign in, choose Use an access token instead. Create a long-lived access token on that user's profile in Home Assistant (Security tab), paste it into Long-lived access token (optional) and choose Test and link. If you link this way, delete the token in Home Assistant too when you remove the connection.

Result

After a sign-in, the Connections tab says Connected. Looking for devices…, then how many devices it found. After a token link, the form says it is connected and how many devices it found; choose Done. Devices are kept up to date live over a constant connection to your instance.

To place devices by their Home Assistant areas, map the areas under Vendor rooms on Settings → Devices (IoT) → Sites And Spaces; see How to Set Up Sites and Spaces.

If it doesn't work

• Use the instance's domain name, not an IP address. Enter the domain name.
• The address must start with https://. Set up HTTPS and use the secure address.
• Only port 443 or 8123 is allowed. Use one of those ports.
• That address does not point to the public internet. The address only works inside your network. Use the address you reach from outside.
• A message says the version is too old: update Home Assistant to 2024.1 or later, then try again.
• Other messages are explained in Fixing a Connection Problem.