C2 Pairing Codes

End-to-end flow

1. You (admin) click Generate below. A code like HEX-PAIR-XK7A2P appears with a 30-minute expiration.
2. Hand the code to the person provisioning the device (could be you walking down the hall, could be a remote staff member over chat).
3. That person powers on the device. Captive portal opens as HexworthDevice-XXXX.
4. They join the AP, fill in: home WiFi network, home WiFi password, device name, pairing code.
5. Device posts to /c2RegisterWithCode. Backend validates the code transactionally (lookup + mark-used + mint device credentials in one Firestore transaction).
6. If valid: device gets its deviceId + deviceKey, code is marked consumed, device appears in the C2 Dashboard.
7. If invalid: device gets HTTP 403 with a reason (unknown / used / expired). User can request a new code.

Why a pairing code at all?

The /c2Register endpoint accepts any POST. Anyone on the public internet who can reach the URL can mint a deviceKey. That's fine for a training-tool demo but unsafe for a real fleet. Pairing codes close that gap by requiring admin involvement before a device can register.

Backwards compatibility

The legacy /c2Register endpoint still works — the c2-device firmware already in the wild keeps registering normally. New firmware should prefer /c2RegisterWithCode. Deprecation of the open endpoint is a future hardening step.

If a code leaks

Codes are single-use and short-lived (default 30 min). A leaked code can claim one device. After that, it's dead. Reduce the TTL further if your provisioning workflow runs faster than 30 min.