Device Provisioning and Onboarding Template

Pre-provision. Create device records in your cloud registry during manufacturing, tied to the device certificate. This means the cloud already "knows" the device when it first connects, which simplifies authentication and prevents unauthorized devices from registering. The alternative (register on first boot) requires a less secure initial authentication mechanism, typically a shared secret or registration token.

Use BLE as the side channel. The companion app connects to the device via BLE, discovers available Wi-Fi networks through the device's radio, and sends the selected SSID and password over the encrypted BLE link. This is the standard pattern for headless IoT devices. Alternatives include WPS (deprecated, security concerns), SoftAP (device creates temporary access point, more complex), and SmartConfig (broadcasts credentials via Wi-Fi, unreliable). For the full UX design, see the [connected device UX template](/templates).

Support ownership transfer through factory reset. The previous owner removes the device from their account (via app or factory reset button). The cloud releases the user binding but preserves the device identity. The new owner provisions the device to their account using the standard setup flow. Historical data from the previous owner should not transfer for privacy reasons. Document this flow clearly in user-facing support articles.

The top three causes of setup failure are: wrong Wi-Fi password (show/hide toggle, paste support), BLE permission issues on the phone (pre-check and prompt before scanning), and user confusion about device state (clear LED indicators for each setup stage). Track setup funnel analytics with step-by-step drop-off rates. For measuring onboarding effectiveness over time, track your [activation rate](/metrics/activation-rate) alongside setup completion rate.

Only if your device has a screen or physical controls sufficient for Wi-Fi credential entry. For headless devices, the companion app is required for setup. A web-based alternative (device hosts a SoftAP, user connects and configures via browser) works but adds complexity and creates a worse experience than a native app. Prioritize the native app flow first. Add a web fallback later if analytics show significant demand from users who refuse to install the app. ---