Provisioning

The provisioning component sets up a provisioning window for devices that ship without their credentials configured — for example, a boxed product whose API encryption key is set by Home Assistant the first time it connects. This helps meet the secure-communication requirements of standards such as EN18031.

The device opens the provisioning window when it boots and closes it once the device is provisioned. A device is considered provisioned once it has connected to a network (over WiFi, Ethernet, or another interface) and, when the API is set up with encryption, its key has been set. If timeout elapses while the device is still unprovisioned, the window closes anyway and the device stops accepting provisioning:

• New API clients are turned away with a “provisioning closed” reason.
• BLE Improv (esp32_improv) stops accepting WiFi credentials. Serial Improv (improv_serial) is left enabled, since it requires a physical connection to the device.
• The on_timeout automation runs.

While the device is unprovisioned, the API and WiFi reboot_timeouts are paused so it does not reboot itself while waiting to be set up. Power-cycling (or pressing a physical reset button) reopens the window.

provisioning:
  timeout: 60s
  on_timeout:
    then:
      - logger.log: "Provisioning window closed; reset the device to reopen it"

At least one provisioning-capable component must be present. A configured network interface such as WiFi or Ethernet satisfies this, as does the API with encryption: and no key:.

Configuration variables

• timeout (Required, Time): How long after boot the provisioning window stays open before closing if the device is still unprovisioned.
• on_timeout (Optional, Automation): An automation to perform when the provisioning window closes.

See Also

• Native API Component
• Improv via BLE
• Improv via Serial
• API Reference: provisioning.h