Langdurig toegangstoken in Home Assistant: aanmaken, waarom van een beheerder en “het werkt maar toont niets”

Het korte antwoord

Een langdurig toegangstoken vervangt het wachtwoord voor apps en scripts: je maakt het aan in je Home Assistant-profiel, op het tabblad Beveiliging, onder Toegangstokens met lange levensduur, en Home Assistant toont het maar één keer. Het is 10 jaar geldig. Sommige apps hebben een token van een beheerder nodig, omdat delen van de API, zoals /api/template, elke andere gebruiker met een 401 weigeren.

De rest van dit artikel loopt elk onderdeel door: wat het token is, waar je het vindt, hoe je het kopieert zonder het te beschadigen, waarom de beheerdersvraag ertoe doet, hoe je een token test met twee curl-opdrachten, en hoe je je tokens onder controle houdt. Het uitgewerkte voorbeeld is AmazHA, een Home Assistant-app voor Amazfit-horloges, omdat die elk van deze punten raakt: hij heeft een token nodig, hij heeft het token van een beheerder nodig, en hij moet omgaan met tokens die door kopiëren en plakken verminkt binnenkomen.

Wat een langdurig toegangstoken is

Een langdurig toegangstoken is een inloggegeven waarmee een programma als jouw Home Assistant-gebruiker kan optreden zonder via het inlogscherm te gaan. Log je in op de webinterface, dan geeft Home Assistant je browser een kort toegangstoken (30 minuten) en een vernieuwingstoken dat het verlengt. Een script, een telefoonapp of een horloge-app kan die inlogprocedure niet makkelijk doorlopen, dus biedt Home Assistant een tweede soort token: een dat je met de hand aanmaakt, één keer kopieert en aan het programma geeft.

Drie eigenschappen tellen in de praktijk:

• Het is 10 jaar geldig. De eigen documentatie van de authenticatie-API van Home Assistant zegt dat langdurige tokens “are valid for 10 years”, en de profielpagina herhaalt het: elk token is 10 jaar geldig vanaf het aanmaken.
• Het wordt één keer getoond. Home Assistant bewaart het token zelf niet, dus het kan het niet opnieuw tonen. Ben je het kwijt, dan maak je een nieuw.
• Het is de gebruiker die het heeft gemaakt. Een token draagt de rechten van de gebruiker die het heeft aangemaakt, niet meer en niet minder. Een token van een beheerder is een beheerder voor elk verzoek dat het ondertekent; een token van een gewone gebruiker is een gewone gebruiker.

Het token reist bij elk verzoek mee in een HTTP-header:

Authorization: Bearer <your token>

Meer hoeft een client niet te doen. Er is geen gebruikersnaam, geen wachtwoord en geen sessie: elk verzoek met een geldig token in die header wordt aanvaard als die gebruiker.

Waar je het vindt

Langdurige toegangstokens maak je aan in je eigen gebruikersprofiel, op het tabblad Beveiliging. In de Home Assistant-app of in een browser:

1. Open de zijbalk (het menu ≡ op een telefoon) en tik onderaan op je naam.
2. Open in je profiel het tabblad Beveiliging.
3. Verderop op dat tabblad staat het gedeelte Toegangstokens met lange levensduur, met de lijst van tokens die je al hebt en een knop Token aanmaken.

De gebruikersdocumentatie van Home Assistant zegt het op dezelfde manier: User profile › Security, de pagina waar je ook je wachtwoord wijzigt, tweestapsverificatie instelt en vernieuwingstokens beheert.

“Ik kan het niet vinden”

De meest voorkomende reden is het tabblad. Het profiel opent op de algemene instellingen (taal, thema en dergelijke); het gedeelte met de tokens staat op het tabblad Beveiliging. Veel oudere handleidingen zeggen dat je naar de onderkant van de profielpagina moet scrollen, wat klopte voordat het profiel in tabbladen werd opgesplitst.

Twee andere redenen:

• Je zoekt het token van iemand anders. Elke gebruiker ziet en beheert alleen zijn eigen tokens. Een token dat een andere huisgenoot heeft aangemaakt, verschijnt niet in jouw profiel, en je kunt het daar niet verwijderen.
• Je bent ingelogd als een andere gebruiker dan je denkt. Controleer de naam onderaan de zijbalk. Heeft een app het token van een beheerder nodig (daarover hieronder meer), zorg dan dat die naam van een beheerder is voordat je het aanmaakt.

Aanmaken en kopiëren

Een token aanmaken kost vier tikken; het goed kopiëren is waar het misgaat. De stappen:

1. Tik op het tabblad Beveiliging, onder Toegangstokens met lange levensduur, op Token aanmaken.
2. Home Assistant vraagt je het token een naam te geven. Gebruik de naam van de app, bijvoorbeeld AmazHA. Namen moeten uniek zijn onder je tokens.
3. Het volgende venster toont het token, met de waarschuwing dat je je toegangstoken moet kopiëren omdat het niet opnieuw wordt getoond. Kopieer het nu, helemaal.
4. Sluit het venster. Het token staat nu in de lijst onder zijn naam, met de dag waarop het is aangemaakt.

Een token is een lange reeks letters, cijfers, - en _, in drie delen gescheiden door punten. Die lengte is de reden dat de meeste kopieerproblemen ontstaan: het past niet op één regel, dus een slordige selectie pakt maar een deel ervan, en sommige apps korten een lange reeks op het scherm in met een weglatingsteken (…) en kopiëren dan wat ze tonen.

Praktische gewoonten die problemen voorkomen:

• Gebruik de kopieerknop in het venster, geen handmatige selectie.
• Plak het direct in de app die het nodig heeft. Een omweg via een chat, een e-mail of een notitie-app kan onzichtbare tekens, typografische aanhalingstekens of regeleinden toevoegen.
• Zet er geen Bearer voor, tenzij de app uitdrukkelijk om de hele header vraagt. Bijna elke app voegt dat woord zelf toe.
• Heb je het op een ander apparaat nodig, maak daar dan een tweede token aan in plaats van het eerste rond te sturen.

Waarom sommige apps het token van een beheerder nodig hebben

Sommige apps hebben het token van een beheerder nodig omdat Home Assistant een paar API-endpoints voor beheerders reserveert, en een token alleen kan wat zijn gebruiker kan. Het duidelijkste voorbeeld is het template-endpoint, POST /api/template, dat een Jinja-sjabloon op de server uitwerkt en het resultaat teruggeeft.

In de broncode van Home Assistant heeft de view die het bedient, APITemplateView in homeassistant/components/api/__init__.py, een post-methode met de decorator @require_admin. Die decorator controleert de gebruiker achter het token; is de gebruiker geen beheerder, dan gooit hij Unauthorized, wat de HTTP-laag van Home Assistant omzet in 401 Unauthorized. De documentatie van de REST-API markeert het endpoint ook als “Admin”.

Het is niet de enige. De REST-API valt grofweg zo uiteen:

Waarom zou een app het template-endpoint dan überhaupt nodig hebben? Omdat sommige informatie niet in de gewone REST-endpoints zit. Het duidelijkste geval zijn de ruimtes: /api/states geeft elke entiteit met haar toestand en attributen, maar niet de ruimte waar ze bij hoort, en de REST-API heeft geen endpoint dat ruimtes opsomt. Een sjabloon kan erom vragen: area_id(entity_id) en area_name(...) geven de ruimte die Home Assistant voor elke entiteit bepaalt, via de eigen instelling van de entiteit of die van haar apparaat. Een app die je huis kamer voor kamer wil tonen, zoals de dashboards van Home Assistant doen, werkt dus een sjabloon uit, en heeft daar een beheerder voor nodig.

Is het een goed idee om een app beheerdersrechten te geven?

Het eigen beveiligingsadvies van Home Assistant is om beheerderstoegang alleen te geven aan accounts die het nodig hebben. Een app die /api/template nodig heeft, is zo’n geval, en je hebt twee redelijke manieren om ermee om te gaan:

• Maak het token aan als je eigen beheerder. De eenvoudigste optie. Het token staat in je profiel onder zijn naam, en als je het verwijdert, trek je alleen de toegang van die app in.
• Maak een aparte beheerder voor de app aan in Instellingen › Personen, log één keer in als die gebruiker en maak daar het token aan. De informatie over het laatste gebruik blijft dan gescheiden van de jouwe, en je kunt de hele gebruiker later uitschakelen. Houd hem actief zolang de app hem gebruikt: de tokens van een gedeactiveerde gebruiker werken niet meer. Vink Local access only niet aan als de app ook van buitenshuis verbinding maakt, om de reden in het gedeelte over de 401 hieronder.

Hoe dan ook verdient het token de zorg die je aan een wachtwoord besteedt: het token van een beheerder kan alles wat jij in Home Assistant kunt.

“Het werkt maar toont niets”: de 401 op /api/template

Maakt een app verbinding en toont hij toch niets, dan is de oorzaak bijna altijd een token van een gebruiker die geen beheerder is. De verbindingstest slaagt, omdat de meeste apps testen met GET /api/ en dat endpoint elk geldig token accepteert. Toestanden lezen lukt ook. Alleen het template-verzoek mislukt, met een 401, en een app die zijn apparatenlijst uit dat sjabloon opbouwt, heeft uiteindelijk niets om te tonen.

Het verloop, vanuit de app gezien:

1. GET /api/ met het token: 200, {"message": "API running."}. De app meldt “verbonden”.
2. GET /api/states/...: 200. De toestanden zijn er.
3. POST /api/template om entiteiten aan ruimtes te koppelen: 401. Geen ruimtes, dus geen kamers, dus een leeg scherm.

Wat het verwarrend maakt, is dat verder niets er fout uitziet. Het adres klopt, het token is geldig, Home Assistant draait. Zelfs acties kunnen werken: POST /api/services/... staat open voor gewone gebruikers, dus met hetzelfde token kan een lamp nog steeds vanuit de app worden geschakeld.

Wat Home Assistant toont

Home Assistant telt elke 401 die het stuurt als een mislukte inlogpoging, ook die van de beheerderscontrole. In het logboek verschijnt een waarschuwing die begint met “Login attempt or request with invalid authentication from …”, met het adres waar het verzoek vandaan kwam (thuis meestal je telefoon of je server), en de webinterface toont een melding Login attempt failed (inlogpoging mislukt). Heb je IP-blokkering aangezet met een aantal inlogpogingen voor een blokkade, dan blokkeren genoeg van die 401’s dat adres: vanaf dan krijgt het voor alles 403 Forbidden, tot je het uit ip_bans.yaml haalt en Home Assistant opnieuw opstart.

Zie je dus herhaaldelijk meldingen over mislukte inlogpogingen die naar je eigen telefoon wijzen, dan is een app met het token van een gewone gebruiker die een endpoint voor beheerders aanroept één verklaring, naast een token dat is verwijderd.

Hoe AmazHA het herkent en meldt

AmazHA, dat je ruimtes via /api/template leest, controleert bewust op dit geval in plaats van je met een leeg horloge te laten zitten:

• Als je op Verbinden tikt, controleert de telefoon eerst het adres met GET /api/ en stuurt daarna één triviaal sjabloon, {{ 1 }}, naar /api/template. Wordt dat sjabloon geweigerd met een 401, een 403 of een 400, dan wordt het token gemarkeerd als niet van een beheerder. Het scherm Home Assistant toont dan Verbonden ✓ met een oranje regel eronder: “Verbonden, maar dit token heeft geen beheerdersrechten, dus het horloge kan je entiteiten niet laden. Maak een langlevend token aan bij een Home Assistant-gebruiker met de rol Administrator en plak het hierboven.”
• Op het horloge, als de kamers niet kunnen worden geladen omdat het ruimtesjabloon wordt geweigerd, toont het startscherm de banner Admin-token nodig · “Je token heeft geen adminrechten — gebruik een Home Assistant-adminaccount”, in plaats van een algemeen Offline.
• In het ondersteuningsrapport dat je vanuit de AmazHA-instellingen kunt sturen, zegt een rij “HA token” of het token als dat van een beheerder werd herkend, zonder het token ooit mee te sturen.

De oplossing is in elk geval dezelfde: maak een nieuw langdurig token aan terwijl je als beheerder bent ingelogd, plak het, en tik opnieuw op Verbinden. Stap 5 van Als er iets misgaat laat het zien in de video.

Zo controleer je of een gebruiker beheerder is

Open Instellingen › Personen en daarna het tabblad Gebruikers. De kolom Groep zegt Administrators (beheerders) bij een beheerder; open je een gebruiker, dan zie je de schakelaar Administrator (beheerder), met de uitleg dat beheerders gebruikers, apparaten, automatiseringen en dashboards kunnen beheren.

Er is een snellere test: heeft de zijbalk van het account waarmee je bent ingelogd helemaal geen item Instellingen, dan is die gebruiker geen beheerder. Home Assistant registreert zijn configuratiepaneel als alleen voor beheerders, dus gewone gebruikers zien het nooit. Log in dat geval uit, log in als beheerder en maak daar het token aan.

Controleer het zelf met curl

Je kunt elk token in een minuut testen vanaf een computer in hetzelfde netwerk, met twee curl-opdrachten: een tegen /api/, waar elk geldig token doorheen komt, en een tegen /api/template, waar alleen het token van een beheerder doorheen komt. De voorbeelden gebruiken 192.168.1.50:8123 als adres van Home Assistant; vervang het door het jouwe. Ze werken zoals ze er staan in een terminal op macOS of Linux.

Om het token uit je shellgeschiedenis te houden, lees je het eerst in een variabele in. Plak het token als de opdracht wacht en druk daarna op Enter:

read -rs HA_TOKEN

Test 1: is het token geldig?

curl -s -w "\nHTTP %{http_code}\n" \
  -H "Authorization: Bearer $HA_TOKEN" \
  http://192.168.1.50:8123/api/

Een geldig token antwoordt {"message":"API running."} en HTTP 200. Let op de slash aan het eind: het endpoint is /api/, niet /api.

Test 2: is het token van een beheerder?

curl -s -w "\nHTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "{{ 1 }}"}' \
  http://192.168.1.50:8123/api/template

Het token van een beheerder krijgt het uitgewerkte sjabloon, 1, en HTTP 200. Het token van een gewone gebruiker krijgt HTTP 401.

Zo lees je de twee resultaten samen:

Twee kanttekeningen. Ten eerste test dit het token vanaf je computer; een app op je telefoon kan een andere route naar Home Assistant nemen, vooral buitenshuis. Ten tweede bewijst een geslaagde test 1 alleen weinig voor apps die ruimtes nodig hebben: het is precies de test die het token van een gewone gebruiker doorstaat.

De 401 van “Local access only”

Een gebruiker met Local access only aan kan alleen vanuit je lokale netwerk inloggen, en Home Assistant past dezelfde regel toe op de tokens van die gebruiker. Een verzoek vanaf een adres buiten je netwerk, of een dat via Home Assistant Cloud binnenkomt, wordt geweigerd met een 401, ook al werkt hetzelfde token thuis perfect. Werkt een app op je wifi en mislukt hij buitenshuis met een 401, open dan de gebruiker in Instellingen › Personen en kijk naar die schakelaar voordat je het externe adres verdenkt. Voor het externe adres zelf, zie Home Assistant buitenshuis op je horloge.

Problemen bij het plakken

Een token dat er goed uitziet, kan toch fout zijn, omdat wat je hebt geplakt niet altijd is wat Home Assistant je gaf. Home Assistant vergelijkt het token teken voor teken, dus één teken te veel of te weinig is een ongeldig token en een 401. De gebruikelijke boosdoeners:

De remedie is voor allemaal dezelfde: kopieer het token opnieuw met de kopieerknop van het venster en plak het direct. Is het venster al gesloten, dan is het token weg; maak een nieuw aan en verwijder de oude vermelding.

Wat AmazHA opschoont, en wat het weigert

AmazHA lost de herstelbare gevallen zelf op, zowel als je het token opslaat als opnieuw wanneer de telefoon het leest om een verzoek te doen:

• Verwijderd: spaties, regeleinden, tekens met nulbreedte, harde spaties, byte-order marks, zachte afbreekstreepjes en richtingstekens, waar ook in het token. Geen ervan kan deel uitmaken van een Home Assistant-token, dat bestaat uit letters, cijfers, -, _ en punten.
• Van de uiteinden gehaald: rechte en typografische aanhalingstekens, backticks en guillemets.
• Aan het begin weggelaten: een geplakt Bearer (in welke schrijfwijze ook), omdat AmazHA dat woord zelf toevoegt.

Wat opschonen niet kan oplossen, is een zichtbaar teken dat in geen enkel token voorkomt, meestal de … van een kopie die is afgebroken. AmazHA gokt niet: het weigert dat token überhaupt te versturen, zodat er geen verzoek Home Assistant bereikt en er geen mislukte inlogpoging wordt geteld. Het scherm Home Assistant in de instellingen toont Token ongeldig, met de uitleg “Het token bevat een teken dat een Home Assistant-token niet kan hebben — meestal een afgebroken kopie (…). Kopieer het volledige token opnieuw uit je Home Assistant-profiel › Beveiliging en plak het hierboven.” Het horloge toont Controleer het token · “Bevat een ongeldig teken — plak het opnieuw”. Dat is stap 6 van Als er iets misgaat.

Houd het veilig

Behandel elk langdurig token als een wachtwoord dat 10 jaar niet verloopt: één token per app, een naam die zegt welke app, en verwijder het op de dag dat je die app niet meer gebruikt. Concreet:

• Eén token per app of apparaat. Geef je hetzelfde token aan drie programma’s, dan kun je er niet één intrekken zonder de andere twee te breken, en kun je niet zien welk ervan een verzoek doet.
• Noem het naar de app. “AmazHA”, “Back-upscript”, “Wandtablet”. De naam is alles wat je later in de lijst ziet; het token zelf wordt nooit meer getoond.
• Kijk af en toe naar de lijst. Elke vermelding toont wanneer het token is aangemaakt en, zodra het is gebruikt, wanneer en vanaf waar het voor het laatst is gebruikt. Een token dat al maanden niemand heeft gebruikt, komt in aanmerking om te verwijderen.
• Intrekken doe je door te verwijderen. Verwijder op het tabblad Beveiliging het token op zijn naam. De app die het gebruikte, mislukt bij zijn volgende verzoek, met een 401; verder wordt er niets aangeraakt.
• Kan een token zijn uitgelekt, verwijder het dan en maak een nieuw aan. Verwijderen is de enige manier om één token in te trekken; de vervanger staat binnen een minuut in de app.
• Plak een token nooit in een ondersteuningsverzoek, een forumbericht of een schermafbeelding. De diagnose van een goede app heeft het nooit nodig.

Als je op hetzelfde tabblad alle vernieuwingstokens verwijdert, worden je apparaten afgemeld, maar blijven de huidige sessie en je langdurige tokens bestaan, zoals het bevestigingsvenster van Home Assistant zegt. Langdurige tokens trek je een voor een in.

In AmazHA

AmazHA heeft precies één langdurig token nodig, van een beheerder, één keer ingevoerd in de AmazHA-instellingen in de Zepp-app; dat ene token dient voor zowel het lokale als het externe adres, en het blijft op je telefoon. De verbindingsvelden zijn beschikbaar zodra de volledige versie is ontgrendeld (een eenmalige ontgrendeling, geen abonnement: zie De volledige versie ontgrendelen). Daarna:

1. Maak het token aan als beheerder, zoals hierboven (stap 1–3 van Home Assistant koppelen).
2. Ga in de Zepp-app naar Profiel › je horloge › Apps › AmazHA › Instellingen en tik op Home Assistant (stap 4).
3. Vul bij Lokale URL (LAN) je adres thuis in, bijvoorbeeld http://192.168.1.50:8123, en, als je wilt dat het horloge ook buitenshuis werkt, het adres van buitenaf bij Externe URL. Elk van de twee velden mag leeg blijven.
4. Plak het token bij Langdurig toegangstoken (stap 7).
5. Tik op Verbinden. Met beide adressen ingevuld toont het resultaat elk ervan, LAN en Extern; met één adres staat er Verbonden ✓. Is het token niet van een beheerder, dan verschijnt eronder de oranje regel die hierboven is beschreven.

Eén token, twee adressen

Voor het externe adres heb je geen tweede token nodig. Een token hoort bij een gebruiker, niet bij een adres: hetzelfde token is geldig, of het verzoek Home Assistant nu via je wifi of van buitenaf bereikt. Thuis gebruikt AmazHA het lokale adres; het externe is alleen voor als de telefoon weg is. De enige uitzondering is de gebruiker met Local access only die hierboven is beschreven, wiens token van buitenaf bewust wordt geweigerd.

Waar het token naartoe gaat, en waar niet

Het horloge praat nooit rechtstreeks met Home Assistant. Dat doet je telefoon, via de Zepp-app, en daar, op de telefoon, wordt het token bewaard. Het wordt alleen naar je Home Assistant-server gestuurd, in de header Authorization van de eigen verzoeken van de telefoon; het wordt nooit naar het horloge gestuurd, dat via zijn Bluetooth-verbinding met de telefoon alleen ontvangt wat het toont. AmazHA heeft geen eigen server waar het token doorheen zou gaan, en het ondersteuningsrapport bevat het nooit.

Wat de telefoon met het token doet, verzoek voor verzoek:

De laatste rij is de functie horlogesensoren, die de hartslag, stappen, batterij en meer van je Amazfit naar Home Assistant stuurt als apparaat van de Mobile App-integratie: Stuur de gegevens van je Amazfit naar Home Assistant behandelt het.

Als AmazHA iets over het token zegt

De kleine code onder Offline is er voor de ondersteuning: schrijf je ons, dan vertelt een foto van het horloge precies wat er misging. Voor elke andere melding die het horloge kan tonen, zie Als er iets misgaat.