Ecobee + Home Assistant

1. Choose Your Method

There are two ways to integrate Ecobee with Home Assistant:

Our recommendation: Use HomeKit Device integration for new setups. It provides local control and doesn't require an API key. If you already have an API key, the native integration offers more features.

2. Method A: HomeKit Device (Recommended)

All Ecobee thermostats support HomeKit, which means you can integrate them locally without Ecobee's cloud API.

Prerequisites

• Ecobee thermostat with HomeKit enabled
• 8-digit HomeKit pairing code (on the thermostat or in Ecobee app)
• Home Assistant on the same network as the thermostat

Finding Your HomeKit Code

Your HomeKit setup code is an 8-digit number. Find it by:

1. On the thermostat: Main Menu → Settings → HomeKit → Show Setup Code
2. Or in the Ecobee app: Settings → [Your Thermostat] → HomeKit

Setup Steps

1. Go to Settings → Devices & Services
2. Click + Add Integration
3. Search for HomeKit Device (not "HomeKit Controller")
4. Enter your thermostat's HomeKit pairing code
5. Home Assistant will pair directly with the thermostat

3. Method B: Native Ecobee API

If you have an existing Ecobee API key, or obtained one before March 2024, this method provides the most complete integration.

Prerequisites

• Existing Ecobee developer account with API key
• Ecobee account with MFA disabled (required for developer portal)

Setup Steps

1. Go to Settings → Devices & Services
2. Click + Add Integration
3. Search for Ecobee
4. Enter your API key
5. Home Assistant will display an 8-character PIN
6. Go to ecobee.com/consumerportal
7. Navigate to My Apps → Add Application
8. Enter the PIN and authorize
9. Return to Home Assistant and submit

4. Available Features

Climate Control (Both Methods)

• Target temperature (heat, cool, or auto with dual setpoints)
• HVAC mode: heat, cool, heat_cool (auto), off
• Fan mode: on, auto
• Climate presets: Home, Away, Sleep, and custom presets

Sensors (Native API Only)

• Room sensors: Temperature and occupancy from each sensor
• Thermostat sensors: Temperature, humidity, outdoor temperature (if weather enabled)

Advanced Controls (Native API Only)

• Vacation management: Create and delete vacation holds
• Smart Away: Toggle automatic away detection
• Humidifier control: When humidifier is connected
• Ventilator: 20-minute activation switch for HRV/ERV systems
• Auxiliary heat: Force aux heat only mode

5. Automation Ideas

Temperature-Based Alerts

automation:
  - alias: "Alert if house gets too cold"
    trigger:
      - platform: numeric_state
        entity_id: climate.ecobee_thermostat
        attribute: current_temperature
        below: 55
    action:
      - service: notify.mobile_app
        data:
          message: "House temperature dropped to {{ states.climate.ecobee_thermostat.attributes.current_temperature }}°F!"

Away Mode When Everyone Leaves

automation:
  - alias: "Set Away when house is empty"
    trigger:
      - platform: state
        entity_id: group.family
        to: "not_home"
        for: "00:15:00"
    action:
      - service: climate.set_preset_mode
        target:
          entity_id: climate.ecobee_thermostat
        data:
          preset_mode: "away"

Boost Heat Before Waking

automation:
  - alias: "Pre-heat before alarm"
    trigger:
      - platform: time
        at: "06:00:00"
    condition:
      - condition: state
        entity_id: input_boolean.workday
        state: "on"
    action:
      - service: climate.set_temperature
        target:
          entity_id: climate.ecobee_thermostat
        data:
          temperature: 72

6. Troubleshooting

HomeKit Pairing Fails

• Ensure the thermostat isn't already paired with Apple Home
• Verify Home Assistant and thermostat are on the same network/VLAN
• Try resetting HomeKit on the thermostat and pairing again

API Integration Disconnects

• Check if your Ecobee account password changed (re-authorize if so)
• Verify MFA is still disabled on your Ecobee account
• The API key may have been revoked (create a new one if you still have developer access)

Thermostat Shows "Unavailable"

• HomeKit: Check WiFi connection on thermostat
• API: Check internet connection and Ecobee server status
• Restart the integration from Settings → Integrations

Room Sensors Not Showing

• Room sensors only appear with the native API integration
• HomeKit integration doesn't expose individual room sensors

7. Frequently Asked Questions

8. Sources

This guide was compiled from official documentation:

• Home Assistant Ecobee Integration (official docs)
• Home Assistant HomeKit Device Integration (official docs)

Last verified: 2026-01-31 against Home Assistant 2026.1. If you find outdated information, let us know.