Home Assistant Long-Lived Access Token erstellen – Schritt für Schritt

Wer Home Assistant mit ioBroker, Node-RED, Grafana oder einem eigenen Skript verbinden will, braucht dafür einen Long-Lived Access Token. Dieser langlebige Zugangs-Token ersetzt Benutzername und Passwort und erlaubt anderen Systemen den Zugriff auf die REST-API und die Entitäten von Home Assistant.

In dieser Anleitung erstellst du in vier Schritten einen Token, testest ihn direkt mit einem einzigen Befehl und trägst ihn anschließend in ioBroker oder Node-RED ein. Am Ende findest du die häufigsten Fehlermeldungen und was dahintersteckt.

Was ist ein Long-Lived Access Token?

Home Assistant meldet dich in der App und im Browser mit einem kurzlebigen Token an, der regelmäßig automatisch erneuert wird. Für ein anderes System funktioniert das nicht – es kann sich nicht alle paar Minuten neu anmelden.

Genau dafür gibt es den Long-Lived Access Token: einen Schlüssel, der zehn Jahre lang gültig ist und bei jeder Anfrage an die API mitgeschickt wird. Technisch ist es ein JSON Web Token (JWT), erkennbar an den Anfangszeichen eyJ.

Drei Dinge solltest du dabei von Anfang an wissen:

• Ein Token gehört immer zu einem Benutzerkonto. Löschst du den Benutzer, werden alle seine Tokens sofort ungültig.
• Ein Token erbt die Rechte dieses Benutzers. Ein Token eines Administrators darf alles.
• Nach dem Schließen des Erstellungs-Fensters lässt sich der Token nie wieder anzeigen. Kopiere ihn sofort.

Home Assistant Token erstellen – in 4 Schritten

Schritt 1: Benutzerprofil öffnen

Klicke in der Seitenleiste unten links auf deinen Benutzernamen. Du landest auf deiner Profilseite.

In aktuellen Home-Assistant-Versionen ist die Profilseite in Reiter aufgeteilt – wechsle dort auf den Reiter Sicherheit. In älteren Versionen findest du den Bereich stattdessen direkt am Ende der Profilseite, wenn du ganz nach unten scrollst.

Schritt 2: Bereich „Langlebige Zugangs-Token“ aufrufen

Ganz unten findest du den Abschnitt Langlebige Zugangs-Token (englisch: Long-Lived Access Tokens). Falls du bereits Tokens angelegt hast, siehst du hier eine Liste mit Namen und Erstellungsdatum.

Klicke auf Token erstellen.

Schritt 3: Namen vergeben

Home Assistant fragt nach einem Namen. Der Name dient nur dir zur Orientierung und hat keinen Einfluss auf die Funktion.

Vergib pro angebundenem System einen eigenen Token mit sprechendem Namen – also ioBroker, Node-RED, Grafana statt einmal Token. Der Grund folgt weiter unten im Abschnitt zum Widerrufen.

Bestätige mit OK.

Schritt 4: Token kopieren und sicher ablegen

Jetzt zeigt Home Assistant den fertigen Token an – eine sehr lange Zeichenkette, die mit eyJ beginnt. Daneben findest du zusätzlich einen QR-Code für mobile Apps.

Kopiere den Token jetzt vollständig und speichere ihn in deinem Passwortmanager. Sobald du das Fenster schließt, ist er nicht mehr einsehbar. Geht er verloren, hilft nur: alten Token widerrufen, neuen erstellen.

Achte beim Kopieren darauf, dass kein Leerzeichen und kein Zeilenumbruch mitkopiert wird – das ist die mit Abstand häufigste Fehlerquelle.

[PRÜFEN: Screenshot 4 – der angezeigte Token, natürlich unkenntlich gemacht.]

Token testen – mit einem Befehl

Bevor du den Token in ein anderes System einträgst, prüfe ihn direkt. Das erspart dir eine lange Fehlersuche im falschen System.

Öffne ein Terminal und setze deine IP-Adresse und deinen Token ein:

curl -H "Authorization: Bearer DEIN_TOKEN" \     -H "Content-Type: application/json" \     http://192.168.1.100:8123/api/

Wenn der Token gültig ist, antwortet Home Assistant mit:

{"message": "API running."}

Damit ist bewiesen: Token, IP-Adresse und Port stimmen. Kommt stattdessen 401: Unauthorized, springe direkt zum Abschnitt über häufige Fehler.

Ein zweiter nützlicher Test fragt den Zustand einer konkreten Entität ab:

curl -H "Authorization: Bearer DEIN_TOKEN" \     http://192.168.1.100:8123/api/states/light.wohnzimmer

Die Antwort enthält den aktuellen Status, alle Attribute und den Zeitpunkt der letzten Änderung.

Token in ioBroker eintragen

Der häufigste Anwendungsfall: ioBroker soll die Entitäten aus Home Assistant lesen und schalten können.

1. Öffne in ioBroker die Instanz-Einstellungen des Home-Assistant-Adapters.
2. Trage bei URL beziehungsweise IP-Adresse die Adresse deiner Home-Assistant-Installation ein, standardmäßig mit Port 8123.
3. Füge den Token in das Feld Access Token ein.
4. Speichere und starte die Instanz neu.

Läuft die Instanz nach dem Neustart grün, erscheinen die Entitäten im Objektbaum.

[PRÜFEN: Genauen Adapternamen und die exakten Feldbezeichnungen aus deiner Installation eintragen. Screenshot der Adapter-Konfiguration ergänzen.]

Eine ausführliche Anleitung dazu findest du im Artikel ioBroker – Zugriff auf Home Assistant Entitäten.

Token in Node-RED verwenden

In Node-RED brauchst du die Palette node-red-contrib-home-assistant-websocket.

1. Ziehe einen beliebigen Home-Assistant-Node auf den Flow und öffne ihn per Doppelklick.
2. Lege beim Feld Server über das Stift-Symbol einen neuen Server an.
3. Trage als Base URL http://192.168.1.100:8123 ein.
4. Füge den Token in das Feld Access Token ein.
5. Bestätige mit Add und setze den Flow mit Deploy aktiv.

Läuft die Verbindung, zeigt der Node unter seinem Symbol den Status connected.

Geräte über die API schalten

Sobald der Token funktioniert, kannst du Home Assistant auch von außen steuern. Ein Licht schaltest du so ein:

curl -X POST \  -H "Authorization: Bearer DEIN_TOKEN" \  -H "Content-Type: application/json" \  -d '{"entity_id": "light.wohnzimmer"}' \  http://192.168.1.100:8123/api/services/light/turn_on

Nach demselben Muster funktioniert jeder Dienst: Der Pfad ist immer /api/services/<domain>/<dienst>, die Nutzlast enthält mindestens die entity_id. Für einen Schalter wäre das switch/turn_on, für ein Rollo cover/open_cover.

Diese Aufrufe lassen sich direkt in Tasker, Apple Kurzbefehlen oder einem Shell-Skript verwenden.

Token widerrufen oder erneuern

Einen Token kannst du jederzeit ungültig machen:

1. Profil öffnen, Bereich Langlebige Zugangs-Token aufrufen.
2. Beim betreffenden Eintrag auf das Löschen-Symbol klicken.
3. Bestätigen.

Der Token ist sofort und ohne Neustart unbrauchbar. Genau hier zahlt sich der eigene Token pro System aus: Ist ein Token kompromittiert, widerrufst du nur diesen einen – die übrigen Anbindungen laufen unverändert weiter.

Ein Token läuft nach zehn Jahren ab. Um ihn zu erneuern, erstellst du einfach einen neuen, trägst ihn im Zielsystem ein und löschst danach den alten.

Sicherheit: wo der Token hingehört – und wo nicht

Ein Long-Lived Access Token ist gleichwertig zu deinem Passwort. Wer ihn hat, kann alles tun, was der zugehörige Benutzer darf.

• Nicht in ein öffentliches GitHub-Repository, ein Forum oder einen Screenshot.
• Nicht per URL-Parameter übergeben – nur im Authorization-Header, wie in den Beispielen oben.
• Für Anbindungen, die nur lesen sollen, lohnt sich ein eigener Home-Assistant-Benutzer ohne Administratorrechte. Dessen Token kann dann deutlich weniger anrichten.
• Wenn du von außerhalb deines Netzwerks zugreifst, sollte die Verbindung zwingend über HTTPS laufen, sonst geht der Token im Klartext durchs Netz.

Häufige Fehler und ihre Ursache

401: Unauthorized Der Token wird nicht akzeptiert. In dieser Reihenfolge prüfen: Wurde beim Kopieren ein Zeichen abgeschnitten oder ein Leerzeichen mitgenommen? Wurde der Token bereits widerrufen? Wurde der Benutzer gelöscht, dem er gehört? Fehlt das Wort Bearer vor dem Token?

Connection refused oder Zeitüberschreitung Hier ist nicht der Token das Problem, sondern die Erreichbarkeit. Prüfe IP-Adresse und Port 8123 und ob das anfragende System überhaupt im selben Netz liegt.

400: Bad Request beim Schalten Die Nutzlast stimmt nicht. Meist ist die entity_id falsch geschrieben – sie muss exakt so lauten wie in den Entwicklerwerkzeugen unter Zustände.

Der Token funktionierte gestern noch Dann wurde entweder der Token widerrufen oder der zugehörige Benutzer gelöscht beziehungsweise deaktiviert. Eine Passwortänderung allein macht bestehende Tokens nicht ungültig.

403: Forbidden Der Token ist gültig, aber der Benutzer darf diese Aktion nicht. Typisch bei einem Benutzer ohne Administratorrechte, der auf einen geschützten Bereich zugreifen soll.

Häufige Fragen

Wie lange ist ein Long-Lived Access Token gültig? Zehn Jahre ab Erstellung. Vorher wird er nur ungültig, wenn du ihn widerrufst oder den zugehörigen Benutzer löschst.

Kann ich einen Token später erneut anzeigen lassen? Nein. Home Assistant zeigt ihn ausschließlich einmal direkt nach der Erstellung. Ist er verloren, musst du einen neuen erstellen.

Wie viele Tokens darf ich anlegen? Beliebig viele. Ein eigener Token pro angebundenem System ist die empfohlene Vorgehensweise.

Muss ich den Token nach einer Home-Assistant-Aktualisierung neu erstellen? Nein, bestehende Tokens bleiben über Updates hinweg gültig.

Bleibt der Token nach einer Passwortänderung gültig? Ja. Nur das Widerrufen des Tokens oder das Löschen des Benutzerkontos beendet die Gültigkeit.