Pairing with hello

With POST /device/hello a device fetches its own token. It gets a pairing code, the owner enters that code in the portal, and the next hello returns the token. Nobody has to copy a key by hand.

Rather not build this? Create a key in the portal and put it on the device yourself: see the end of this page.

The flow#

1. The device generates a random uuid (version 4) once and keeps it, across restarts too.

2. It sends POST /device/hello, without a token:

   {"device_uuid": "7b0e2f4c-1d3a-4e5b-9c6d-8f7a6b5c4d3e", "hw_serial": "00000000abcd1234", "firmware_version": "0.3.0"}
   

   Only device_uuid is required; hw_serial may be up to 64 characters, firmware_version up to 32.

3. As long as nobody has paired the device, it gets a pairing code:

   {"claimed": false, "pairing_code": "BB-7KQ4-M2XD", "expires_at": "2026-10-10T12:00:00+00:00"}
   

   The device shows the code, for example on a display or in a log.

4. The owner enters the code: on the device page with Pair with code, or under New device in Pairing code (optional).

5. On its next hello, the device receives its token:

   {"claimed": true, "token": "bb_live_42_Xk3…"}
   

6. The device stores the token and uses it. From then on, hello only answers {"claimed": true}.

The uuid and the code#

• A uuid of any version other than 4, such as one built from time and MAC address, gets 422.
• Keep the uuid secret until the token has been used: whoever knows it can collect the token once the device is paired. So don't print it on a sticker or write it to a log others can read.
• Send a hello about every 15 seconds while you wait. The same uuid gets the same code until it expires, 24 hours after the first answer.
• A code is BB- followed by two groups of four characters, without 0, O, 1 and I. Capitals, spaces and dashes don't matter in the portal. After ten wrong codes in an hour, the portal refuses every code until the hour is up.

Store it first, then use it#

Until the token has been used once, every hello returns a new token and the previous one stops working. So a lost answer is no problem: just ask again. Stick to this order:

1. Store the token so it survives a power cut: write to a temporary file, then rename it.
2. Use it straight away, with GET /device/config or POST /device/status. Pairing is then complete.
3. Don't send hello after that. If you do before the token's first use, your stored token stops working.

Lost the token after using it? Then hello with the same uuid no longer helps. Generate a new uuid, get a new code and enter it with Pair with code on the page of the same device. Or create a key by hand.

What pairing does in the portal#

• Only someone who manages the device can enter a code, not someone it is merely shared with.
• Pairing with a code switches off the device's current API key immediately. The device fetches a new one with its next hello.
• If you delete the device, hello with the same uuid starts over, with a new code.
• A simulated device cannot be paired with a code.

A key made by hand#

On the device page, on Settings under Connection, there is a Create key button, or New key if there already is one. The portal asks for your password first and shows the key once. If you add a device without a pairing code, you get a key straight away.

A key made by hand closes the pairing. The next hello with that uuid gets a new code, and nothing the device does with hello will switch off your key.

Limits#

What	Limit
hello per uuid	10 per minute
hello per IP address	30 per minute. An IPv6 /64 network counts as one address

Over a limit you get 429 with a Retry-After header: wait that many seconds. 422 means a missing or invalid device_uuid, or a field that is too long. See also Limits and error codes and the API reference.