Koppelen via hello

Met POST /device/hello haalt een apparaat zelf zijn token op. Het krijgt een koppelcode, de eigenaar vult die in het portaal in, en bij de volgende hello komt het token. Niemand hoeft dan een sleutel over te typen.

Liever niet bouwen? Maak dan een sleutel in het portaal en zet die zelf op het apparaat: zie onderaan.

Het verloop#

1. Het apparaat maakt één keer een willekeurige uuid (versie 4) en bewaart die, ook over herstarts heen.

2. Het stuurt POST /device/hello, zonder token:

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

   Alleen device_uuid is verplicht; hw_serial mag tot 64 tekens zijn, firmware_version tot 32.

3. Zolang niemand het apparaat heeft gekoppeld, krijgt het een koppelcode:

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

   Het apparaat toont de code, bijvoorbeeld op een scherm of in een log.

4. De eigenaar vult de code in: op de pagina van het apparaat met Koppelen met code, of bij Nieuw apparaat in Koppelcode (optioneel).

5. Bij de volgende hello krijgt het apparaat zijn token:

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

6. Het apparaat bewaart het token en gebruikt het. Daarna antwoordt hello alleen nog {"claimed": true}.

Uuid en code#

• Een uuid van een andere versie dan 4, zoals een uuid uit tijd en MAC-adres, krijgt 422.
• Houd de uuid geheim tot het token gebruikt is: wie hem kent, kan na het koppelen het token ophalen. Dus niet op een sticker en niet in een log die anderen zien.
• Stuur ongeveer elke 15 seconden een hello terwijl je wacht. Met dezelfde uuid krijg je dezelfde code, tot die 24 uur na het eerste antwoord verloopt.
• Een code is BB- plus twee keer vier tekens, zonder 0, O, 1 en I. Hoofdletters, spaties en streepjes maken in het portaal niet uit. Na tien foute codes in een uur weigert het portaal elke code tot dat uur om is.

Eerst bewaren, dan gebruiken#

Tot het token één keer gebruikt is, geeft elke hello een nieuw token en werkt het vorige niet meer. Een verloren antwoord is dus geen probleem: vraag opnieuw. Houd daarom deze volgorde aan:

1. Sla het token op zodat het een stroomstoring overleeft: eerst naar een tijdelijk bestand, dan hernoemen.
2. Gebruik het meteen, met GET /device/config of POST /device/status. Dan is het koppelen klaar.
3. Stuur daarna geen hello meer. Doe je dat vóór het eerste gebruik, dan werkt je opgeslagen token niet meer.

Token kwijt na gebruik? Dan helpt hello met dezelfde uuid niet meer. Maak een nieuwe uuid, vraag een nieuwe code en vul die in bij Koppelen met code op de pagina van hetzelfde apparaat. Of maak een sleutel met de hand.

Wat koppelen in het portaal doet#

• Alleen wie het apparaat beheert, kan een code invullen, niet iemand met wie het alleen gedeeld is.
• Koppelen met een code zet de huidige API-sleutel direct uit. Het apparaat haalt met zijn volgende hello een nieuwe op.
• Verwijder je het apparaat, dan begint hello met dezelfde uuid opnieuw, met een nieuwe code.
• Een gesimuleerd apparaat kun je niet met een code koppelen.

Een sleutel met de hand#

Op de pagina van het apparaat staat op Instellingen onder Verbinding de knop Sleutel aanmaken, of Nieuwe sleutel als er al een is. Het portaal vraagt eerst je wachtwoord en toont de sleutel één keer. Voeg je een apparaat toe zonder koppelcode, dan krijg je meteen een sleutel.

Een sleutel met de hand sluit het koppelen af. De volgende hello met die uuid krijgt een nieuwe code, en niets wat het apparaat met hello doet, zet jouw sleutel uit.

Limieten#

Wat	Limiet
hello per uuid	10 per minuut
hello per IP-adres	30 per minuut. Een IPv6-/64-netwerk telt als één adres

Daarboven krijg je 429 met een Retry-After-header: wacht zo veel seconden. 422 betekent een ontbrekende of ongeldige device_uuid, of een veld dat te lang is. Zie ook Limieten en foutcodes en de API-referentie.